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Introduction 


Welcome to THINK’s Lightspeed Pascal (THINK Pascal). This chapter tells you about THINK 
Pascal, what’s in your THINK Pascal package, what equipment you need, and what you need 
to know to start writing Pascal programs on the Macintosh. 


Before you begin 

Be sure to fill out and return the registration card that came with your THINK Pascal package. 
Registering insures that you'll get the technical support you need, and that you'll be notified 
of revisions and upgrades to THINK Pascal. 


If you don’t read manuals 
To get started quickly, read this chapter, the next chapter, and do one of the tutorials. 


If you’re an experienced THINK Pascal user 

If you already use THINK’s Lightspeed Pascal, you'll be pleased with the new features in this 
release. Read “Notes for Experienced Users” at the end of this chapter to learn what's new in 
THINK Pascal. 


Topics covered in this chapter 
e What is THINK’s Lightspeed Pascal 
¢ What you need 
¢ What's in the package 
e¢ What's in the manual 
¢ What you should know 
¢ Notes for experienced users 


What is THINK’s Lightspeed Pascal? 


THINK’s Lightspeed Pascal is a unique development environment for the Macintosh. It fea- 
tures a very fast compiler, a faster linker, an integrated text editor designed specifically for 
Pascal syntax, an auto-make facility, advanced debugging tools, and a project organizer that 
holds all the pieces together. Because the editor, the compiler, and the linker are all compo- 
nents of the same application, THINK Pascal knows when edited source files need to be re- 
compiled. If you edit the interface section of a unit, the auto-make facility recompiles only 
the source files that depend on it. 
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With THINK Pascal you can build Macintosh applications, desk accessories, device drivers, 
and any kind of code resource. The standard Pascal libraries include the standard I/O func- 
lions like writeln so you can use Pascal programs that were written for other computers. 


THINK Pascal lets you run your program as you work on it. Your program runs as if you had 
opened it from the Finder, You can use the debugging tools built into THINK Pascal to make 
sure your program runs correctly. The debugger lets you set breakpoints, step through your 
code, examine variables, and change their values — even structured variables like records 
and arrays— while your program is running. 


THINK Pascal is fast. So fast that it will change the way you program. Not only are the com- 
piler and the linker many times faster than other development systems, they are part of an in- 
tegrated package that also includes an editor, debuggers, an automatic “project manager” that 
keeps track of your edits, and only recompiles source files that have changed since the 
program was last built. 


THINK ’s Lightspeed Pascal is a remarkable product that delivers the efficiency and power 
you need, THINK Pascal will seem natural and obvious — the way things ought to be. 


A development environment that works with you 


In traditional development environments, the edit-compile-link-run loop takes so long that 
is impractical to make a small change just to see how it works. Because it takes so long to 
compile and link, programmers tend to make several changes at once to get more “bang for 
the buck.” Unfortunately, when your program crashes, you have to figure out which one of 
the small changes actually caused the crash. The “bang” gets very expensive. 


Because THINK Pascal is so fast, you can make a small change, compile and link your pro- 
gram, and run it to see the effect before traditional development environments even start 
linking. And because your program is running in the controlled THINK Pascal environment, 
you don’t have to worry about most of the common crashes. THINK Pascal is right there to 
catch you so you can start fixing your code without restarting your Macintosh, 


In traditional development environments, you have to keep track of various language objects 
such as source files, object files, a link-control file, an executable image, and administrative 
files. ‘THINK Pascal takes care of all this bookkeeping for you. In THINK Pascal, you have 
only your source files, library files, and a project document. The project document serves 
as an on-line project administrator for your program development. THINK Pascal keeps track 
of whatever changes you make to your source files, automatically compiling and linking 
wherever necessary, so all you have to do is edit your program and run. 


A rich set of debugging tools 


Not only does ‘THINK Pascal help you develop your program faster, it also helps you debug 
your program faster. THINK Pascal has a rich set of powerful debugging tools. 


The integrated editor catches syntax errors and pretty-prints (formats) your program as you 
type it in. THINK Pascal lets you run your program a statement at a time or in slow motion. 
You can stop your program any time it’s running, or you can set breakpoints anywhere in 
your program. 


The Observe and LightsBug windows let you examine and change the values of your vari- 
ables — even structured variables like records and arrays. The Instant window lets you try 
out small pieces of code to see how they'd work in your program. 


Advanced features let you stop at Macintosh Toolbox routines, and you can even use a low 
level debugger like TMON or Macsbug. 


What You Need 


THINK Pascal works best when you have at least 1 megabyte (Mb) of RAM and a hard disk. It 
will also run with two 800K floppy drives. 


How much RAM? 


You can run THINK Pascal on a Macintosh Plus, Macintosh SE, or Macintosh Il. You can run 
THINK Pascal on a Macintosh 512Ke if you’ve upgraded it to at least 1Mb of RAM, 


How much disk space? 

The complete THINK Pascal system takes up about 800K on your disk, not including your 
own files. The actual size of your system may be smaller, depending on the kinds of pro- 
grams you work on. 


Although you can use THINK Pascal with two 800K floppy drives, it works much better when 
you use a hard disk. 


Which System and Finder? 


Use the latest System and Finder. At press time, this is System Tools 6.0 (System 6.0/Finder 
6.1). THINK Pascal requires at least System Tools 5.0 (System 4.2/Finder 6.0). 


What’s in the Package 


Your THINK Pascal package consists of two double sided floppies and this manual. 
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What’s in the Manual 


‘This manual is organized in five sections: Getting Started, Learning THINK Pascal, Using 
THINK Pascal, Reference, and Appendices. Each chapter begins with an introduction that 
describes what's in the chapter, followed by a list of the major topics covered in the chapter. 


Getting Started This is the section you're reading. It contains this chapter and 
the installation instructions. Even if you don’t read manuals, be 
sure to read the installation instructions in Chapter 2. 


Learning THINK Pascal ‘This section contains three tutorials, The first one, “Bullseye,” 
shows you how to write a program in THINK Pascal and how 
to use the basic debugging tools. 


The second tutorial, “ObjectDraw,” shows you how to build a 
Macintosh application in THINK Pascal. It covers some of the 
more advanced topics like using resource files and libraries. 


The third tutorial, “ObjectDraw DA,” shows you how to build a 
desk accessory in THINK Pascal. It covers even more ad- 
vanced topics like segmentation. 


Using THINK Pascal This section contains ten chapters that describe the different 
components of THINK Pascal. 


Editing, Chapter 6, describes the THINK Pascal editor which is 
specifically designed to help you write Pascal programs. 


Working With Projects, Chapter 7, is about projects, the orga- 
nizing tool that keeps track of all your source files and object 
code. You'll learn how to work with source files, how to add 
them to your project, and how to segment your project. 


Running Programs, Chapter 8, shows you how to run a pro- 
gram in THINK Pascal, You'll learn how to compile and link 
your program, and what to do when something goes wrong. 


Debugging Programs, Chapter 9, introduces you to the basic 
set of debugging tools in THINK Pascal. These tools let you 
run your program line by line, set breakpoints anywhere in 
your program, and observe the values of your variables. 


Units and Libraries, Chapter 10, teaches you how to create 
units and libraries. Units and libraries are collections of Pascal 


code that help you write modular programs. 


Using Predefined Routines, Chapter 11, tells you how to use 
the procedures and functions built into THINK Pascal. It also 
tells you how to call the Macintosh Toolbox routines. 


Building Projects, Chapter 12, shows you how to build the four 
kinds of programs you can write in THINK Pascal: applica- 
tions, desk accessories, device drivers, and code resources. 


Assembly Language, Chapter 13, gives you all the information 
you need to know to write assembly language routines that 
work with THINK Pascal. 


LightsBug, Chapter 14, introduces you to LightsBug, THINK 
Pascal’s powerful debugging tool. LightsBug lets you get a 
closer look at your program. You can examine and change the 
values of your variables (even arrays and records), look at any 
part of memory, and examine the heap. 


Compiler Directives, Chapter 15, shows you how to use com- 
piler directives — instructions to the compiler — to generate 
different code for different situations. 


Reference This section contains two reference chapters. 


THINK Pascal Menus, Chapter 16, describes the THINK Pascal 
menu commands. 


Language Reference, Chapter 17, describes the Pascal lan- 
guage implemented by THINK Pascal. This is a very long 
chapter, and you don’t have to read all of it. The important 
sections are sections 9 and 10 which describe the built in in- 
put/output routines and the standard routines. 


Appendices This section contains six appendices. 


ANS Pascal Compatibility, Appendix A, describes THINK 
Pascal’s compatibility with the ANS Pascal standard. 


Porting to THINK Pascal, Appendix B, describes the limitations 
and non-standard features of THINK Pascal that you need to 
be aware of when you port programs from other Pascals to 
THINK Pascal. 
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BackupProject, Appendix C, describes a utility that makes 
backups of all the files in your project. 


RMaker Reference, Appendix D, shows you how to use the re- 
source compiler. 


Error Messages, Appendix E, lists and describes all the error 
messages that THINK Pascal generates. 


Macsbug Reference, Appendix F, shows you how to use 
Macsbug, a low level debugger. 


If you are interested in a specific topic, consult the index in the back of the manual. 


Conventions in the manual 
The names of menus and commands are in bold face. 


When a technical term or key word is introduced, it also appears in bold face. 


Names of files, code fragments, resource names, function names, and variables appear in 
“typewriter face.” 


All numbers are decimal. Hexadecimal numbers are written in Pascal notation: $3EFA. 


In this manual, the term Toolbox routine means any routine in ROM, The Macintosh ROM 
actually consists of two kinds of routines: Operating System routines and Toolbox routines. 
Operating System routines deal with low-level aspects of the machine like the file manager, 
the event posting mechanism, device management, etc. The Toolbox deals with high-level 
aspects like the drawing environment, the window mechanism, menus, dialogs, etc. 


What You Should Know 


‘This manual assumes you know how to use your Macintosh, and that you already know or 
are at least learning, how to program in Pascal. If you're just getting started in Pascal, THINK 
Pascal is a great platform. 


If you're planning to write Macintosh applications, you should be familiar with the Macintosh 
Toolbox as described in Inside Macintosh. The Toolbox is the set of operating system and 
user interface routines that make a Macintosh a Macintosh. This manual won't show you how 
to write Macintosh applications or how to use the Macintosh Toolbox. There are several 
books that teach you how to build applications — see “Learning to write Macintosh pro- 
grams” below. You can also look at the sample programs in your THINK Pascal package for 
examples of Macintosh applications. 


One of the best ways to learn both Pascal and Macintosh programming at the same time is 
with Just Enough Pascal, an on-line programming tutorial. Just Enough Pascal is a desk 
accessory that works with THINK Pascal to teach you Pascal, Macintosh programming, and 
THINK Pascal right at your Macintosh. 


Learning Pascal 


Pascal is the most popular language for learning how to program, so you'll find several books 
that teach programming in Pascal. Some of the Pascal books are written specifically for use 
with THINK’s Lightspeed Pascal or its cousin, Macintosh Pascal. 


The standard reference for the Pascal programming language is the third edition of Pascal 
User Manual and Report (Springer-Verlag) by Kathleen Jensen and Niklaus Wirth, revised by 
Andrew Mickel and James Miner. The User Manual and Reportis fairly technical, and it’s de- 
signed for people who already know fundamental programming concepts. 


Scott Kronick’s Macintosh Pascal Illustrated: The Fear and Loathing Guide (Addison-Wesley) 
is an amusing and unorthodox introduction to programming the Macintosh in Pascal. His 
book covers most of the things you need to know to get started. 


Ob! THINK’s Lightspeed Pascal (WW. W. Norton) by George Beekman and Michael Johnson is a 
companion to Oh! Pascal (W. W. Norton) by Doug Cooper and Michael Clancy. Together, 
these books are a good introduction to Pascal and THINK Pascal. 


Another good book if you’re learning Pascal is Macintosh Pascal (Houghton-Mifflin), by 
Robert Moll and Rachel Folsom. It is particularly helpful because of the many similarities be- 
tween Macintosh Pascal and THINK Pascal. 


If want to learn Object Pascal, see Kurt Schmucker’s Object-Oriented Programming for the 
Macintosh (tlayden). This book contains a great deal of information about object-oriented 
programming in general and some details about using Object Pascal. 


Learning to write Macintosh programs 

If you're new to programming the Macintosh, you might find yourself overwhelmed by the 
complexity of the Macintosh Toolbox and unfamiliar programming techniques. When the 
Macintosh was released in 1984, there was very little technical information available to casual 
programmers, and even commercial developers had a hard time figuring out how to get 
things to work correctly. The Macintosh is even more complex today than it was in 1984, but 
now there are more places you can go for information. 


There are now several good books that introduce you to programming the Macintosh and 
teach you some of the finer points of using the Macintosh Toolbox. No matter which books 
you choose to help you get started, Inside Macintosh is indispensable. 


Inside Macintosh Volumes I-V (Addison-Wesley) is the official reference that describes the 
more than 600 Macintosh Toolbox routines. You might be able to get by without it for a 
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while, but if you're planning to write serious applications, you just can’t do without. At five 
volumes, it represents a hefty investment. The first three volumes cover the fundamentals. 

Volumes IV and V cover the additions and changes made with the introduction of the Mac 
Plus, Macintosh SE, and Macintosh II. 


If you want to to use SANE (Standard Apple Numerics Environment), a copy of Apple 
Numerics Manual, Second Edition (Addison-Wesley) is as indispensable as Inside Macintosh. 


Stephen Chernicoff's two volume set, Macintosh Revealed (Hayden Books), is a step-by-step 
introduction to Macintosh programming. Chernicoff shows you how to build a working ap- 
plication and points out the parts of Inside Macintosh you really need to know as opposed to 
the parts you just need to be aware of. The programs in the book are written in Pascal, so 
you'll have no trouble using THINK Pascal with his books. 


Scott Knaster, formerly of Apple Technical Support, is the author of two books about 
Macintosh programming. The first, Wow to Write Macintosh Software (Hayden Books), 
teaches you what’s going on inside the Toolbox. This book also contains some valuable tips 
about debugging Macintosh programs. The second book, Macintosh Programming Secrets 
(Addison-Wesley), deals with some of the conventions and techniques that have become 
standard in writing Macintosh programs. It also contains information about the Macintosh II 
and the Mac SE. These books are more technical than Macintosh Revealed and are loaded 
with pictures, diagrams, and examples (as well as some awful jokes). 


Finally, MacTutor is the leading technical journal for Macintosh programming. The articles 
range from tutorial examples to advanced techniques. MacTutor covers several languages, 
not just Pascal, and most of the Pascal examples have instructions for building them with 
‘THINK Pascal. (All of the programs described in the magazine are available on disk.) 


Apple Programmer’s and Developer’s Association 

The Apple Programmer's and Developer's Association (APDA) is an Apple-sponsored mem- 
bership organization that distributes technical information to programmers and developers. 
APDA is a great source for Technical Notes, programming utilities, reference books, and in- 
formation about announced (but unreleased) products. For information about membership 
and products, contact APDA directly: 


Apple Programmer's and Developer's Association (APDA) 
290 SW 43rd Street 

Renton, WA 98055 

(206) 251-6548 


CompuServe 


Symantec has a forum on CompuServe specifically for THINK Pascal users. Simply type GO 
THINK al any ! prompt. (You'll be in the LVTFORUM, but that’s OK. It’s the right place.) 
You'll find discussions here about programming in general and THINK Pascal in particular. 


The data libraries contain utilities as well as sources for some of the programs. When up- 
grades are ready, they’re usually posted here first. 


CompuServe also has an Apple developers forum. Just type GO APPDEV atany ! prompt. 
This forum is a good place to get in touch with the Macintosh programming community. 


Technical Support 


If you have questions as you use THINK Pascal, and you can’t find an answer to your ques- 
tion in the manual, call the THINK Pascal Technical Support number: (617) 275-1739. 


Notes for Experienced Users 


If you’ve used THINK’s Lightspeed Pascal before, you’ll be pleased with the new features in 
this new release. This section describes the changes and enhancements. 


Compatibility 
THINK Pascal 2.0 uses a different format for project documents, source files saved as Entire 
Document, and libraries. 


If you saved source files as Entire Document in THINK’s Lightspeed Pascal 1.x, you 
must save them as Text Only before you can use them in THINK Pascal 2.0. 


THINK Pascal 2.0 uses a different format for libraries. If you have built libraries for THINK 
Pascal and you still have the source files, the best thing to do is to rebuild it with THINK 
Pascal 2.0. If you don’t have the source files, use the Convert .lib => 2.0 program in 
the disk THINK Pascal 1. To learn how to build libraries, see Chapter 10. 


The names of the default libraries have changed. MacPasLib.lib is now called Runtime.lib. 
MactTraps is now called Interface.lib, See Chapter 11 to learn about the libraries included with 
THINK Pascal, 


You cannot use Instant and Observe windows that you saved with THINK Pascal 1.x in 
THINK Pascal 2.0. 


New features 


‘THINK Pascal 2.0 includes many new features. One of the most important new features, 
though, is invisible: THINK Pascal now generates much smaller code. You'll notice that your 
finished applications are now 20% smaller. 


Other new features include: 


‘Improved editing The editor features custom pretty-printing, multi-file searching, 
and some new commands for moving around files. It’s also 
faster. See Chapter 6. 
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Improved linking 


Conditional compilation 


Improved LightsBug 


Language extensions 


Large arrays 


Larger projects 


MultiFinder support 


Object Pascal 


Project types 


Smart linking is smarter, and a link errors window lets you see 
all the link errors at once. 


THINK Pascal now lets you define compiler variables for 
conditional compilation. See Chapter 15. 


LightsBug now lets you examine and alter variables, even 
structured variables. LightsBug also lets you set watchpoints so 
your program stops whenever the value of a variable changes. 
See Chapter 14. 


THINK Pascal now supports the CYCLE, EXIT, and LEAVE 
procedures, short-circuit booleans, |-value casting, repeated 
parameter lists in units, constant expressions, subranges in 
case slatements, and UNIV parameters. See Appendix B to 
learn more about the language extensions. 


THINK Pascal 2.0 lets you define array types larger than 32K. 


Projects can now contain up to 255 files. Each unit can 
reference up to 255 other units. Source files can now be much 
larger than before. 


THINK Pascal 2.0 runs under MultiFinder and supports all of 
the Toolbox routines in Inside Macintosh -V. 


THINK Pascal 2.0 supports the Object Pascal extensions. See 
the tutorials programs described in Chapters 4 and 5 for 
examples of Object Pascal programs, 


THINK Pascal lets you build applications, desk accessories, 

device drivers and code resources. Drivers and desk acces— 
sories can have global data and can use Object Pascal. Code 
resources can have custom headers. 
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Introduction 


This chapter tells you how to install THINK’s Lightspeed Pascal on your Macintosh. THINK 
Pascal works best when you have a hard disk. You can use it with two 800K floppies, but you 
may run out of disk space when you start working on large programs. 


Before you begin 


Be sure that you have the proper equipment. You need at least 1 megabyte of RAM, and at 
least wo 800K floppies. See the “What You Need” section in Chapter 1 for more details. 


Make sure that your original THINK Pascal disks are write-protected; move the little tab in the 
corner so you can see daylight through it. Before you do anything, make backup copies of 
your THINK Pascal disks, and use only the backup disks to install THINK Pascal on your 
Macintosh. 


Topics covered in this chapter: 
¢ Installing on a hard disk system 
¢ Installing on a floppy system 


Installing THINK Pascal on a Hard Disk System 


This section tells you how to set up THINK Pascal on your hard disk. This setup makes it 
easicr for THINK Pascal to know where its libraries are. 


Installation summary 


First you'll create a folder for THINK Pascal. The folder will contain THINK Pascal and the 
libraries. When you start working on your own projects, you'll usually want to put them in 
their own folders. 


The picture at the end of this chapter shows you what this disk layout looks like. You can use 
the picture to set up your disk, or you can follow these directions. 


Installation instructions 
Start at the Finder and create a new folder. Name it THINK Pascal Folder. 
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Now, copy these files from disk THINK Pascal 1 to the THINK Pascal Folder: 


* THINK Pascal (the application) 
¢ Interface.lib 
* Runtime.lib 


Note: These three files are the core of the THINK Pascal system. 


Next, copy the Libraries folder and the Interfaces folder from THINK Pascal 1 to the 
THINK Pascal Folder, These folders contain additional libraries and their interface files. 
Depending on the kinds of projects you want to build, you may not need these libraries. See 
Chapter 11. to learn what these additional libraries are for. 


If you want, you can copy the Utilities folders from the two disks to the THINK Pascal Folder. 
The Utilities folders contain ResEdit, RMaker, Macsbug, an application called BackupProject 
which lets you back up all the files in a project and a desk accessory called @Edit which lets 
you edit text files, 


Installing on a Floppy System 


Although THINK Pascal works best when you use a hard disk, you can use it with two 800K 
floppy drives. If you use floppies, you probably like to put your application and a System 
folder on one floppy and all of your data files on another. This is exactly what you'll do with 
THINK Pascal. 


Note: This section assumes that you know what a System folder is and how 
to create startup disks. To learn about startup disks, see Macintosh System 
Software User's Guide that came with your Macintosh. 


Making the System Folder 
First, create the smallest possible startup disk. You can use the Installer in the Mini System 
Sctup Folder on the Macintosh Utilities 1 disk that came with your Macintosh, or you can 


create a folder called System Folder and drag a System and a Finder from another startup disk 
into it. 


Next, drag an ImageWriter driver into the System Folder. Use the ImageWriter that came on 
your Macintosh Printing Tools disk or an ImageWriter from another startup disk. Drag a copy 
of the Font/DA Mover from your Macintosh Utilities 2 disk to the new startup disk. 


Restart your Macintosh using the startup disk you just created. 


Open the Chooser desk accessory from the Apple menu. Make sure that the ImageWriter is 
selected and that it is connected to the correct port. Close the Chooser window. 


Installing THINK Pascal 2 


Use the Fonl/DA Mover to remove all the fonts except the ones needed by the system. Just 
select all the font names, and click on the Remove button. You'll get a warning dialog telling 
you the system fonts won't be removed. 


While you’re still in the Font/DA Mover, insert THINK Pascal 1 and install the @Edit 
desk accessory into your startup disk. Select all the other desk accessories and remove them. 


Quit the Font/DA Mover, and drag it into the trash. 


You should now have the smallest possible system on your startup disk. Here’s a check list to 
make sure everything went OK: 


Files System 
Finder 
ImageWriter 


Desk Accessories @Edit 


Fonts Chicago 12 
Geneva 9 
Geneva 10 
Monaco 12 


Making the THINK Pascal Folder 


Now you're ready to make the THINK Pascal folder. Create a new folder called THINK Pascal 
Folder, and copy these three files from THINK Pascal 1 toit: 


* ‘THINK Pascal (the application) 
¢ Interface.lib 
* Runtime.lib 


As you work with THINK Pascal, you'll put your projects on a second work disk. If you need 
to use any of the additional libraries, copy them to your work disk and load them from there. 


Other floppy layouts 

If you want to create a larger startup disk, you can try using the startup disk as your “data” 
disk and using a THINK Pascal disk in the external drive. You build your project on the 
System disk instead of on the THINK Pascal disk. 


Another thing you might want to keep in mind is that once THINK Pascal has loaded a library 


into a project, it doesn’t need the copy on disk anymore. You can create a “preloaded” 
project and use copies of it. 
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If you use two 800K floppies for most of your work, you’ve probably become very creative 


about managing disk space. You can probably think of other ways to arrange your floppy 
disks. 


Disk Layout Diagram 


This diagram shows the recommended disk layout. You don’t have to set up your disk this 
way, but you should keep the standard libraries in the same folder as THINK Pascal. 
(AboutBox is the name of a program you might be working on.) 
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PART TWO 


Learning THINK Pascal 


3 Tutorial: Bullseye 
4 Tutorial: ObjectDraw 
5 Tutorial: ObjectDraw DA 


Tutorial: Bullseye 
3 


Introduction 


This chapter shows you how to write a program with THINK’s Lightspeed Pascal. The pro- 
gram, called Bullseye, draws a series of concentric circles in the built-in Drawing window. 
This chapter shows you how to create a THINK Pascal project, how to write a Pascal source 
file, and how to use some of the more common debugging tools in THINK Pascal. 


Before you begin 


Be sure you followed the instructions in Chapter 2 to install THINK Pascal on your disk. If 
you’re using two floppy drives, the program in this chapter takes up about 87K. 


What you should know 

You should know how to use the standard file dialog boxes to move around to different 
folders. If you don’t know how to do this, read the Macintosh System Software User’s Guide 
that came with your Macintosh. 


Topics covered in this chapter: 
¢ Creating the project 
¢ Creating a source file 
¢ Adding the source file to the project 
* Running the program 
¢ Debugging the program 
¢ Stepping through the program 
¢ Where to go next 


Creating the Project 


The first thing you need to do is to create a folder for your project. Use the Finder’s New 
Folder command to create a new folder. Name it Bullseye Folder. You can use a 
different name if you like, but remember that your dialog boxes won't match the pictures in 
this chapter. 


Note: Creatc the Bullseye Folder now before you start THINK Pascal. 
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Generally speaking, you'll have a folder for each project that you work on. The folder will 
contain the THINK Pascal project document, all your source files, and your application’s re- 
source file. 


After you create the Bullseye Folder, double-click on the THINK Pascal icon. 


You'll see a dialog box that asks you to open a project: 


J) THINK Pascal 


© GeeGaws 
© Interfaces 
© Libraries 


© utilities 


l sll 


Since you're creating a new project, click on the New button. 


You'll see another dialog box, one that lets you create projects. 
Move to the Bullseye Folder you just created. 


Note: It’s very important to move to the Bullseye Folder. 


Tutorial: Bullseye K] 


Name the project Bullseye.m, and click on the Create button. (To make a “nr” hold down the 
Option key as you press the letter “p”.) 


i Bullseye Folder 


Create the project: 


Bullseye. 


By convention, project documents end in . 1. 


THINK Pascal creates a new project document on the disk and displays a project window. 
Use the size box to make the project window a little smaller, so it looks like this: 


Bullseye. 
Options File (by build order) Size 


Runtime.lib 
Interface lib 


The Options column lets you control some of the compiler options. You'll see how these 
work later in this chapter. The File column shows you the name of each file. The Size col- 
umn shows you the size of the code of each file and library in bytes. 


Note: The notation “by build order” means that the project window is 


showing you the files in the order they’ll be compiled. You'll learn more 
about this in Chapter 5. 
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‘THINK Pascal automatically inserts the names of two standard libraries into your project. 
Runtime .1ib contains the code for all the standard Pascal routines (like writeln). 
Interface.1ib contains the glue code for all the Macintosh Toolbox routines marked 
(Not in ROM]. 


You'll use these two libraries in most of the programs you write. To learn more about li- 
braries, read Chapter 10 and Chapter 11. 


Creating a Source File 


Now you're ready to create your source file. Choose New from the File menu. You'll see an 
empty edit window: 


Untitled 1 


Tit 


Tutorial: Bullseye 3 


Type this program into the editor window: 


Untitled 1 


program Bullseye; 
const 
scale = 8; 
var 
hPos, vPos: integer; 
Radius, i: integer; 
begin 
ShowDrawing 
ho 100; 
yPo 100; 
FenMode(patsor); 
for i = 10 downto 1 do 
begin 
Radius =i * Scale; 
PaintCircle(hPos, vPos, Radius) 
end 
end. 


Note: Make sure you type in the program exactly as it appears above. 
Remember, in Pascal punctuation is very important. 


21 


THINK’s Lightspeed Pascal 


As you type, you’ll notice that the THINK Pascal editor formats (pretty-prints) your program 
for you. If you make a syntax error, the editor points it out by outlining the error text: 


Untitled 1 


program Bullseye; 
const 
soale = $; 
var 


hPos WPS 8 fntener; 


Aside from the special pretty-printing feature, the THINK Pascal editor works much like other 
text editors on the Macintosh. You can drag to select a range of text or double-click to select 
words. If you have a keyboard with arrow keys, you can use them to move around the file. 
To learn more about the THINK Pascal editor, see Chapter 6. 


Tutorial: Bullseye 3 


When you’ve typed in the program, choose the Save As... command from the File menu to 
save it. You'll see a dialog box like this one. Name the file bullseye. p, and click on the 
Save button. 


J Bullseye Folder 
Dy Bulleeie a Tess 


Liect 


Gripe 


Save ‘Untitled 1' as 


bullseye.p Cancel 


@) Text Only 
© Entire Document 


By convention, Pascal source files end in .p. 


Note: The Text Only and Entire Document radio buttons give you two dif- 
ferent ways to save your files. When you click on Entire Document, THINK 
Pascal saves the file in a format that is easier to load later. The disadvantage 
is that you won’t be able to read the file with a “vanilla” text editor. For more 
information about this feature see Chapter 6. 


Adding the Source File to the Project 


After you save your source file, the only thing you have to do is add it to your project. Use 
the Add Window command in the Project menu. 
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Your project window should now look like this: 


Bullseye. HE 

Options File (by build order) Size [A 
Runtime .lib 
Interface Jib 


YOR bullseye.p 


Since neither of the libraries has been loaded, and the one source file hasn’t been compiled, 
the Size column reads zero. 


Running the Program 


Now you're ready to run your program. Choose Go from the Run menu. 


Because it’s an integrated environment, ‘!1IINK Pascal knows that it needs to load the li- 
braries and that it needs to compile your source file. You'll see a dialog box that lets you 
know when THINK Pascal is loading or compiling. 


Compiling "bullseye.p". 


k= | 


0 lines 1? 


Type #-. to cancel the operation. 


Tutorial: Bullseye 3 


When your program runs, it will open the drawing window and draw the bullseye design: 


Wil 


= Drawing >>] 


If you look at the project window now, you'll see that the Size column now contains the sizes 
of the libraries and of your compiled code. 
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Debugging the Program 


‘This program doesn’t have any bugs in it, so to debug it, you'll have to introduce a bug. The 
bug will make THINK Pascal multiply two numbers so the result exceeds the legal range for 
integers. 


First, click on the project window to make it the active window. Next, click on the V and the 
R next to the bullseye. p entry. Now both letters should be outlined with a box: 


Bullseye.11 
Options File (by build order) Size 


Runtime.lib 18080 
Interface.lib 8104 


[eT] bullseye.p 184 


When you click on these two letters, you tell THINK Pascal to generate additional code to 
check for arithmetic overflow and for range checking. Range checking means that THINK 
Pascal checks to make sure that indices to arrays stay within in the bounds of the array, and 
that values assigned to subrange types stay within subrange. 


Tutorial: Bullseye K} 


Now, change the program so the constant scale is equal to MaxInt. MaxInt is a built-in 
constant that’s equal to the largest allowed integer (32767). 


bullseye.p 


program Bullseye; 
const 
scale = Maxint; 
var 
hPos, vPos: integer; 
Radius, i: integer ; 


begin 
ShowDrawing ; 
hPos = 100; 
yPos = 100; 
PenMode(patXor); 
for i = 10 downto 1 do 
begin 


Radius =i * Scale; 
PaintCircle(hPos, vFos, Radius) 
end 
end. 


Now choose Go from the Run menu. THINK Pascal recompiles the program, and then dis- 
plays this dialog box: 


Do you want to save the changes to 
"pullseye.p" before running? 


THINK Pascal noticed that you had not saved the file. You can run the changed program 
without saving the file. In this case we know there’s a bug, so we don’t want to save the file. 
Click on the No button. 
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Immediatcly after the program begins, you'll see a bug dialog: 


t Integer overflow 
progra , 
const 
scale =TTSRmT 
yar 
hPos, ¥Pos: integer; 
Radius, i; integer; 
begin 


hP 

vP 100; 

PenMode(patior); 

for i := 10 downto {| do 

begin 

fs Radius := i # Seale; 

PaintCircle(hPos, vFos, Radius) 
end 
end, 


THINK Pascal puts a “thumbs down” next to the offending line. In this case, it’s telling you 
that the multiplication i*Scale was out of the range for integers. 


‘To dismiss the bug box, click anywhere or press the Return or Enter key. 
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The easiest way to undo the change you made to your file is to go back to the last saved ver- 
sion of the file. Choose the Revert command from the File menu. You'll see this dialog box: 


Revert to the previous version of 
“pullseye.p"? 


—————————— 


IL 


Since you do want to go back to the last saved version, click on the OK button, You'll be 
ready to learn how to use THINK Pascal's debugging tools to step through your program. 


Stepping Through the Program 


THINK Pascal lets you step through your program one line at a time so you can watch what 
it's doing. You can also watch the values that variables take on to make sure your program is 
behaving properly. 


First, make the edit window about half as wide as it is now so it doesn’t obscure the Drawing 
window. Next, choose Observe from the Windows menu. The Observe window appears. 


‘Type in the word Radius, then press Return. Type in the letter i, then press Return. These 
are the names of the variables you'll be observing as you step through the program. 


Observe 


Enter an expression 


Drag the Observe window so it’s above the Drawing window. It’s OK if it overlaps the project 
window. 
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Now choose Step from the Run menu. THINK Pascal draws an execution finger next to the 
first line of your program. Keep choosing step — better yet, use the Command-S equivalent 
—and watch what happens. The execution finger points to each line of the program. As you 
step, watch the values in the Observe window when the execution finger enters the loop. 


(reff 
aes 
I 


bullseye.p 


program Bullseye; 
const 
scale = 8; 
var 
hPos, vPos: integer; 
Radius, i: integer; 
begin 
ShowDrawing; 
hPos := 100; 
yPos := 100; 
PenMode(patXor); 
for i := 10 downto 1 do 
begin 
Radius = * Scale; 
PaintCircle(hPos, vPos, Radius) 


Ki end 


Enter an expression 


Every lime your program stops, THINK Pascal updates the values in the Observe window. 


After you get tired of stepping, choose the Trace command in the Run menu. When you 


choose this command, THINK Pascal runs your program in slow motion, pausing after each 
line. 


Where to Go Next 


The tutorial in the next chapter is a more elaborate example. It shows you how to build a 


double-clickable Macintosh application, and some of the more advanced features of THINK 
Pascal. 


If you would rather explore on your own, read the chapters of the “Using THINK Pascal” 


section that interest you. They're designed to be read in order, but you can skip around if you 
like, 
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Introduction 


This tutorial shows you how to put together a Macintosh application in THINK Pascal. The 
application you'll build is called ObjectDraw. It’s a simple drawing program that lets you 
draw several kinds of shapes in a window. ObjectDraw lets you print the window to any 
printer, and it lets you save your picture as a PICT format file that you can edit with drawing 
programs. 


ObjectDraw shows you how to use resource files with your THINK Pascal programs. It also 
shows you how to add some of the special libraries to your project and how to use compiler 
variables for conditional compilation. 


ObjectDraw uses Object Pascal, but this tutorial won't show you how to use Object Pascal. 
You can look at the code for ObjectDraw to see how to write Object Pascal programs. 


Before you begin 

Make sure that you followed the instructions in Chapter 2 for installing THINK Pascal on your 
Macintosh. For this tutorial, you'll be using files in the Libraries folder and in the Interfaces 
folder as well as the Interface.1ib library. Look at the picture at the end of Chapter 2 to 
see how to arrange your files. 


Copy the folder ObjectDraw Folder from disk THINK Pascal 2 to your disk. This folder 
contains all the source files and resource files that you'll use in this tutorial. It doesn’t really 
matter where you put this folder on your disk as long as you don’t remove any files from it 
and as long as you know where it is. 


Topics covered in this chapter 
* Creating the project 
¢ Adding the libraries 
¢ Adding the source files 
* Setting the Compile Options 
¢ Setting the Run Options 
¢ Building the application 
e Where to go next 
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Creating the Project 


Since you've already copied the ObjectDraw Folder to your disk, you don’t need to create a 
new folder for the ObjectDraw project. All you need to do now is double-click on the THINK 
Pascal icon to launch THINK Pascal. 


‘THINK Pascal displays this dialog when you launch it from the Finder. 


=] THINK Pascal 


© GeeGaws coTess 
© Interfaces = 
© Libraries Eject 
2 Utilities rive 


Cancel 


You're creating a new project, so click on the New button. 
THINK Pascal displays a standard file dialog that lets you create projects. 
Move to the ObjectDraw Folder that you copied from your THINK Pascal disk. 


Note: It’s very important to move to the ObjectDraw folder. 


Name the new project Object Draw.7, and click on the Create button. (To make a “nx” hold 
down the Option key as you press the letter “p”.) 


&j ObjectDraw Folder 


~ 


Gy hie ct Pascal Beme Tess 
Gb ac Beme BR = 

hic emo b feet 

: Ghiec Moemo.p 


ae ihe 
Ghia eme Rsre 


i Ghiec tBemoae/A Bulld 
Create the project: 
ObjectDraw.n 


By convention, all THINK Pascal projects end in .1. 


‘THINK Pascal creates a new project document on the disk and displays a project window. 
Your project window should look like this: 


2 ==> objectdraw.n 
Options — File (by build order) ize 


Runtime Jib 
Interface Jib 


Next, you'll add the libraries to your project, and then you'll add the source files. 
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Adding the Libraries 


‘THINK Pascal automatically inserts the names of two standard libraries into your project. 
Runtime. 1ib contains the code for all the standard Pascal routines (like writeln). 
Interface. 1ib contains the glue code for all the Macintosh Toolbox routines marked 
(Not in ROM]. 


ObjectDraw is a tue Macintosh application, so it doesn’t use any Pascal input/output rou- 
tines. If you leave the Runtime. 1ib library in your project, your program will run perfectly, 
but there will be code in your project that ObjectDraw never uses, and your project file will 
be bigger than it really needs to be. 


THINK Pascal has a smaller version of Runtime. 1ib called wRuntime.1ib which doesn’t 
include the Pascal standard input/output code. To replace Runtime. 1ib with 
HRuntime.1ib, hold down the Option key as you double-click on Runtime. 1ib in the 
project window. THINK Pascal displays this dialog: 


J Ob jectDraw Folder 


rie 


fhaage tp 


Tutorial: ObjectDraw 4 


Runtime. lib is in the Libraries folder, so move to that folder, select URuntime. lib, 


and click on the Change to button. 


pRuntime.lib 
ABPackage.lib 
DRURRuntime.|ib 
FixMath.lib 
Graf3D.lib 
nAppletalk.lib 
SANELib.1ib 
SANELibD881.lib 


D 
D 
D 
D 
D 
a 
D 
D 


Gripe 


Change to 


When you use LRuntime.1ib, you can’t use the THINK Pascal input/output routines like 
reset, rewrite, writeln, readln, etc. If you plan to write Macintosh applications ex- 
clusively, it’s a good idea to use WRuntime.1ib instead of Runtime.1lib to make your 


projects smaller. 


Note: Whether you use Runtime. 1ib or WRuntime.1ib, your finished 
application will be the same size because THINK Pascal uses smart linking 
to remove references to unused code in your final application. The differ- 
ence is only in the project size. 


ObjectDraw uses one more library, PrintCalls.1lib. This library contains the routines for 
the Toolbox Print Manager. To add it to your project, use the Add File... command in the 


Project menu. 


PrintCalls.1ib is in the Libraries folder. Since you're already there, just select it, and 


click on the Add... button. 
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ABPackage.lib 
DRURRuntime.lib 
FixMath.lib 
Graf3D.lib 


nAppletalk.lib 
PrintCalls.lib 
SANELib.1ib 
SANELID881.lib 


DOBODUOUOUDCD 


After THINK Pascal adds a file to your project, it displays the Add File... dialog again so you 
can keep adding files without having to choose Add File... from the menu over and over 
again, 


Don't click on the Cancel button yet because you still have to add the source files to your 
project. 


Note: If you accidentally clicked on the Cancel button, just choose Add 
File... from the Project menu again. 


Adding the Source Files 


Now you'll add the source files to your project. You should still have the Add File... dialog 
on your screen, If you don’t, just choose Add File... from the Project menu. 


Tutorial: ObjectDraw 4 


The first source file you'll add is the interface file for the PrintCalls.1ib library. Move to 
the Interfaces folder, select MacPrint .p, and click on the Add... button. 


&) Interfaces 


D AppleTalk.p Tess 
CD FisMath.p 


D Grat3o.p 


QO MacPrint.p ( fsdnse 


CD MemtTypes.p 

D Objintf.p 

DC OSIntf.p 

D Packlintf.p 

CD PaletteMgr.p Cancel 


The next file you want to add is in this folder, too. Select Obj Int f .p and click on the Add... 
button. This file contains the most primitive object class, TObject. 


Note: You don’t have to add Ob jIntf.p to your project to use Object 
Pascal. You do need it if you define your objects in terms of TObject like 
ObjectDraw does. 


There’s one more file in the Interfaces folder to add to your project. Look for the file 

Script .p, and click in the Add... button. This file is the interface for the Script Manager de- 
scribed in Inside Macintosh V. ObjectDraw doesn’t use the Script Manager, but the interface 
file contains the definition of the function GetMBarHeight which ObjectDraw uses to fig- 
ure out where to position its windows. 


Now move back to the ObjectDraw Folder. The rest of the source files are in this folder. Add 
the source files in this order: 


UDemoUtils.p 
UDPInstall.p 
UDemoLDef.p 
UDemoObjects.p 
UAboutBox.p 
ObjectDraw.p 
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If you discover that you’ve made a mistake in the order that you add the files, don’t worry. 
After you’ve added all the files to the project, just click on a file name and drag it to the 
proper position. To learn more about arranging files in projects, see Chapter 7. 
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Note: Files have to appear in the project in a particular order because Pascal 
requires that you define something before you use it. 


This is what each of the files do. You might want to print them out to study them, but for this 
tutorial that’s not necessary. 


UDemoUtils.p 


UDPInstall.p 


UDemoLDef.p 


UDemoObjects.p 


UAboutBox.p 


ObjectDraw.p 


This file contains all the global variables for the project as well as 
some utility routines. 


This routine contains a utility routine that lets you use definition 
functions like WDEFs, LDEFs, CDEFs, etc. without actually having 
to write the code resources. ObjectDraw uses this routine for the 
LDEF that defines the tool palette. 


ObjectDraw uses the List Manager (see Inside Macintosh IV, 
Chapter 30, “The List Manager Package”) to implement its tool 
palette. This file contains the code for the list definition function. 


This file is the workhorse of the ObjectDraw application. It con- 
tains all the objects and methods for drawing shapes in a window. 


Every application needs a nifty About... box. This file contains the 
code for ObjectDraw’s About... box. 


This file is the main program. It calls the initialization routines and 
sets things in motion. 
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Your project window should look like this now: 


BRuntirne lib 
Interface.lib 
PrintCalls.lib 
MacPrint.p 
Objintf.p 
Script.p 


UDernoUtils.p 
UDP Install.p 
UDemoLDef.p 
UDemoObjects.p 
UAboutBox.p 
ObjectDraw.p 


Setting the Compile Options 


The ObjectDraw source files are structured so you can use many of the same source files for a 
desk accessory version of the program. Applications and desk accessories are quite different, 
but if you modularize your program correctly, you can use the same code for both. In the 
next chapter, you'll build ObjectDraw as a desk accessory. 


There are a few cases where a function has to work differently if the program is a desk 
accessory. For instance, the way you get resources for a desk accessory is quite different from 
getting a resource for an application. ObjectDraw uses a function called RsrcID to get the 
correct resource ID of a resource. If the program is an application, the function returns the ID 
unaltered. If the program is a desk accessory, the function uses the rules for converting a re- 
source ID into an owned resource ID. 
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ObjectDraw uses conditional compilation to compile different ways in an application and in a 
desk accessory. If the compiler variable DeskAcc is defined as true, THINK Pascal com- 
piles the special desk accessory code for this function. This is what the function looks like: 


function RsrcID (id: Integer): Integer; 
var 
i: Integer; 
drvrID: Integer; 


begin 
i := id; 
{SIFC DeskAcc} 
drvrID := abs(drvrRefNum) - 1; 
i := (BOR($C000, id + (BSL(drvrID, 5)))); 
{ SENDC} 
RsrcID := i; 
end; 


Note: To learn about owned resources, see Inside Macintosh I, Chapter 4, 
“The Resource Manager.” To learn about compiler variables, see Chapter 15. 


THINK Pascal lets you define compiler variables with the Compile Options... command. 
Choose Compile Options... from the Project menu. You'll see this dialog: 


Compile Options 


Compile-Time Variables Code Generation 


THINK PASCAL=TRUE; | Ly pA Panee 
Elems881=TRUE; CL] McC68020 


SET OF Integer 
@ 0..255 
© -32768 .. 32767 


Cancel 
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THINK Pascal defines two symbols for you. THINK_PASCAL is always defined as true. You 
can use this symbol if you need to know that your program is being compiled in THINK 


Pascal. The symbols Elems8 81 is used to generate code for the MC68881 math coprocessor 
See Chapter 15 to learn more. 


To build the ObjectDraw application, you want to define two compiler variables, DeskAcc 
and DAProject, and set them both to false. Just type the names in like this in the dialog: 


Compile Options 


Compile-Time Variables 


Code Generation 


THINK_PASCAL=TRUE; LC] Mc6sest 
Elems881=TRUE; C1 Mc6s020 
DeskAcc=FALSE; 


DAProject=FALSE; 


SET OF Integer 
@ 0..255 
© -32768 .. 32767 


=| 


When both of these compiler variables are set to false, THINK Pascal won't compile any of 
the special code that applies only to desk accessories. 
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Setting the Run Options 


The last thing you have to do before you run the project is to make sure that the project 
knows where its resources are. Choose the Run Options... command in the Run menu. 
You'll see this dialog box: 


Run-time Environment Settings 


L] Use resource file: 
Resources - 
for resources used by the project. 


Text Window saves [5000 |characters 


Text LJ Echo to the printer 


Hello world. ™« = 611.79. 


[Monaco 


Stack size:|[EMM|kilobytes 0K | 
Zone size:|256 |kilobytes Cancel | 


Memory 
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Click on the Use resource file: check box. You'll see a standard file dialog. Select Ob- 
jectDraw.Rsrc and click on the Use button. 


&) ObjectDraw Folder 


& ObjectDraw cs Tess 
CD ObjectDraw DA 


B ObjectDraw.Rsrc 
D ObjectDraw/DA Build.1 
D ObjectDraw/DA.W 

D Ob jectDraw/DA.Rsre Mere Sere ee 


Stack size:[16 |kilobytes 
Zone size: kilobytes Cancel 


Memory 


The resource file Ob ject Draw. Rsre was created with ResEdit. You can use ResEdit to look 
at or change some of the resources. 


Note: A RESOURCE FILE USED BY A PROJECT MUST BE IN THE SAME 
FOLDER AS THE PROJECT. 
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Running the Project 


Now you're ready to run the project. Choose Go from the Run menu. THINK Pascal loads all 
the libraries and compiles all the source files. When it finishes compiling, THINK Pascal 
launches the ObjectDraw application. 


Object Window-1 


If you like, you can click on the bug spray can in the far right of the menu bar to halt the pro- 
gram so you can use THINK Pascal’s debugging tools. 


Building the Application 


Once you're sure that the ObjectDraw application runs correctly, build it as a double-click- 
able application. This application will have its own icon in the Finder. In order for the Finder 
to display an application's icon, you have to give the application a signature. 


Tutorial: ObjectDraw 4 


Choose Set Project Type... in the Project menu. Set the creator to RS$$. 


File Information 


& Type: Creator: {& Bundle Bit 


Reseurce Information 


Ell Name 


Desk Accessory 


Driver 


Type: i 


F i > > 
Code Resource uRi-Segment Cancel 


Note: Make sure that you set the creator to RS$$. If you don’t, the Finder 
won't display ObjectDraw’s icon. RS$$ are the initials of the developer who 
wrote ObjectDraw (Rich Siegel). The $$ is there because he’s Rich, 


Make sure that the Bundle Bit check box is checked. 
The Finder uses the signature, the BNDL, FREF, ICN#, and RS$$ resources in ObjectDraw’s 


resource file to give an application an icon. Inside Macintosh Il, Chapter 1, “The Finder 
Interface” describes the mechanism in detail. 


45 


THINK’s Lightspeed Pascal 


46 


You're finally ready to build the application. Choose Build Application... from the Project 
menu. You'll see a dialog box asking you to name the application. Name the application 
ObjectDraw. 


) ObjectDraw Folder 


& Obie tDraus Tess 
iy Ghiaed tBraus BR 
Ghiec Braus 


Riect 
Gh jac 2D raus.p Hive 


Ghiee rads Kore 
Gb ie< (Braws/ 8 Bul... 


Save Application as 


ObjectDraw Cancel 


Smart Link 


When the Smart Link check box is checked, THINK Pascal makes sure that the final ap- 
plication is as small as possible by stripping out any code that the application doesn't need. 


After THINK Pascal finishes building your application, quit to the Finder, and look in the 
ObjectDraw folder. There you'll see your new application’s icon. 


Cea] 


ObjectDraw 


Double-click on it to make sure it works. Congratulations! You’ve built a real Macintosh 
application. 


Where to Go Next 


The next chapter shows you how to build the same program as a desk accessory. If you want 
to keep’ playing with ObjectDraw, read Chapter 9 and Chapter 14 to learn how to use THINK 
Pascal’s debugging tools. If you want to start creating your own programs skip to the “Using 
THINK Pascal” section, 


Tutorial: ObjectDraw DA 
5 


Introduction 


This tutorial shows you how to test and build a desk accessory in THINK Pascal. The desk 
accessory is the same ObjectDraw program that you built in the last tutorial. Some of the in- 
structions in this tutorial are the same as for building the application version, so you'll be fa- 
miliar with the process. This tutorial takes you step by step, so if you didn’t build the applica- 
tion version, you'll still be able to create the desk accessory. You might want to take a glance 
over at the previous chapter before you begin, though. 


Building a desk accessory is a little more difficult than building an application, and this tuto- 
rial will introduce you to some new concepts and commands fairly quickly. You may want to 
skim the tutorial first before you start to make sure you're ready. 


Before you begin 
If you followed the tutorial in Chapter 4 you're all set for this tutorial. ObjectDraw DA uses 
many of the same files that you used for the ObjectDraw application. 


Make sure that you followed the instructions in Chapter 2 for installing THINK Pascal on your 
Macintosh. For this tutorial, you'll be using files in the Libraries folder and in the Interfaces 
folder as well as the Interface. 1ib library. Look at the picture at the end of Chapter 2 to 
see how to arrange your files. 


Copy the folder ObjectDraw Folder from disk THINK Pascal 2 to your disk. This folder 
contains all the source files and resource files that you'll use in this tutorial. it doesn’t really 
matter where you put this folder on your disk as long as you don’t remove any files from it 
and as long as you know where it is. 


Topics covered in this chapter 
¢ Writing desk accessories 
¢ Creating the project 
e Adding the libraries 
¢ Adding the source files 
¢ Setting the Compile Options 
¢ Setting the Run Options 
¢ Segmenting the project 
¢ Setting the Project Type 
¢ Building the desk accessory 
¢ Where to go next 
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Writing Desk Accessories 


Desk accessories and applications are structurally quite different. A desk accessory is a small 
program that runs as the “guest” of an application. (If you’re using MultiFinder, the DA 
Handler is the “host” program.) While applications get their events from the Toolbox’s Event 
Manager, desk accessories get their events directly from the system. Desk accessories need to 
be able to respond to certain conditions — the host application quitting, for instance — that 
don’t apply to applications. 


To debug a desk accessory, you have to fool THINK Pascal into thinking that the desk acces- 
sory is actually an application. The DA Shell, included in your THINK Pascal package, is de- 
signed to provide an environment that looks like an application to THINK Pascal and that 
looks like a host application to your desk accessory. 


In this tutorial, you'll learn how to use the DA Shell to debug your desk accessories. ‘he main 
point to remember is that you test your desk accessory in one environment and you build it 
in another. It may sound hard at first, but it’s really not. All it takes is a couple of extra steps. 


Creating the Project 


Since you've already copied the ObjectDraw Folder to your disk, you don’t need to create a 
new folder for the ObjectDraw DA project. All you need to do now is double-click on the 
‘THINK Pascal icon to launch THINK Pascal. 


Tutorial: ObjectDraw DA 5 


THINK Pascal displays this dialog when you launch it from the Finder. 


[ 3] THINK Pascal 


0 GeeGaws coTess 
© Interfaces 

© Libraries 

2 Utilities 


You're creating a new project, so click on the New button. 
THINK Pascal displays a standard file dialog that lets you create projects. 
Move to the ObjectDraw Folder that you copied from your THINK Pascal disk. 


Note: It’s very important to move to the ObjectDraw folder. 
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Name the new project ObjectDraw DA.1, and click on the Create button. (To make a “nx” 
hold down the Option key as you press the letter “p”.) 


<4] ObjectDraw Folder 


Gh lac (Brads Tess 
iy Ghiec trad: BR 
GR jac (Be nies 48 
a REED Hive 


tiect 


Gh hac (Brads Ror 
: GR iae UB reese 


Create the project: 
ObjectDraw DA. 


By convention, all THINK Pascal projects end in .1. 


THINK Pascal creates a new project document on the disk and displays a project window. 
Your project window should look like this: 


ObjectDraw DA.W 
Options File (by build order) Size a 


Runtirne Jib 
Interface Jib : 


Next, you'll add the libraries to your project, and then you’ll add the source files. 


Adding the Libraries 


THINK Pascal automatically inserts the names of two standard libraries into your project. 
Runtime. 1ib contains the code for all the standard Pascal routines (like writeln). 
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Interface.1ib contains the glue code for all the Macintosh Toolbox routines marked 


(Not in ROM]. 


If you went through the tutorial in the last chapter, you remember that it’s better to use the 
Runtime. lib library when you're writing real Macintosh applications — that is, applica- 
tions that don’t use any Pascal standard input/output routines. Well, the fact of the matter is 
that you can’t use the Pascal input/output routines in desk accessories anyway. 


When you're writing desk accessories, you use another library called DRVRRuntime. lib. 
This library is designed specifically for programs that are not applications: desk accessories, 
device drivers, and code resources. The difference between URuntime.1ib and 
DRVRRuntime.1ib is that DRVRRuntime.1ib uses register A4 instead of register A5 to 
access global variables. You don’t have to know what this means to write desk accessories, 
but if you’re interested, look at Chapter 12. 


When you're testing your desk accessory with the DA Shell (which you’re about to do), you 
use [LRuntime. lib. After you've tested your desk accessory, and it’s time to build it, you 
use DRVRRuntime.1ib. This sounds more difficult than it is. Here’s a chart that makes 


things clearer: 


When you're... 
Building an application that uses 
standard Pascal input/output 


Building a Macintosh application 
that doesn’t use Pascal in- 
put/output 


Testing a desk accessory with the 
DA Shell 


Building a desk accessory 


You use... 
Runtime. 1ib (the default) 


wRuntime.lib 


pRuntime.lib 


DRVRRuntime.lib 


51 


THINK’s Lightspeed Pascal 


If you're still not clear about all this library stuff, don’t worry. This tutorial takes you step by 
step so you can’t make a mistake. 


Now you need to replace Runtime. 1ib with WRuntime.1ib. Hold down the Option key 
as you double-click on Runtime. 1ib in the project window. THINK Pascal displays this di- 
alog: 


©] ObjectDraw Folder] 
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Runtime. 1ib is in the Libraries folder, so move to that folder, select tRuntime. lib, 
and click on the Change to button. 


= 


uRuntime.lib Tess 
ABPackage.lib 
DRURRuntime.|lib £}GCR 
FixMath.lib 
Graf3D.lib 
nAppletalk.lib 
SANELib.1ib Change to 
SANELib881.1ib 


rive 


ODOOODOCDODOLRE 


Cancel 


L 


ObjectDraw DA uses one more library, PrintCalls.1ib. This library contains the routines 
for the Toolbox Print Manager. To add it to your project, use the Add File... command in the 
Project menu. 
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PrintCalls. lib is in the Libraries folder. Since you're already there, just select it, and 
click on the Add... button. 


OC ABPackage.lib Tess 
O DRURRuntime.|ib = 

DC FixMath.lib £ ject 
CO Graf3D.lib 


$ rive 
CB nfppletTalk.lib 


D PrintCalls.lib 
DC SANELIib.1ib 
CQ SANELib881.1ib 


After THINK Pascal adds a file to your project, it displays the Add File.., dialog again so you 
can keep adding files without having to choose Add File... from the menu over and over 
again. 


Don't click on the Cancel button yet because you still have to add the source files to your 
project. 


Note: If you accidentally clicked on the Cancel button, just choose Add 
File... from the Project menu again. 


Adding the Source Files 


Now you'll add the source files to your project. You should still have the Add File... dialog 
on your screen. If you don’t, just choose Add File... from the Project menu. 
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The first source file you'll add is the interface file for the PrintCalls.1ib library. Move to 
the Interfaces folder, select MacPrint .p, and click on the Add... button. 


& Interfaces 


D AppleTalk.p 
D FisMath.p 

D Graf3D.p 

CO MacPrint.p 


CO MemtTypes.p 
D Objintf.p 

D OSIntf.p 

D Packlintf.p 

CD PaletteMgr.p 


The next file you want to add is in this folder, too. Select Obj Int f .p and click on the Add... 
button. This file contains the most primitive object class, TObject. 


Note: You don’t have to add ObjInt£.p to your project to use Object 
Pascal. You do need it if you define your objects in terms of TObject like 
ObjectDraw does. 


Now move back to the ObjectDraw Folder. The rest of the source files are in this folder. Add 
the source files in this order: 


UDemoUtils.p 
UDPInstall.p 
UDemoLDef.p 
UDemoObjects.p 
UAboutBox.p 
ObjectDraw/DA.p 


If you discover that you’ve made a mistake in the order that you add the files, don’t worry. 
After you've added all the files to the project, just click on a file name and drag it to the 
proper position. To learn more about arranging files in projects, see Chapter 7. 


Note: Files have to appear in the project in a particular order because Pascal 
requires that you define something before you use it. 
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This is what each of the files do. You might want to print them out to study them, but for this 
tutorial that’s not necessary. 


UDemoUtils.p This file contains all the global variables for the project as well as 
some utility routines. 


UDPInstall.p This routine contains a utility routine that lets you use definition 
functions like WDEFs, LDEFs, CDEFs, etc. without actually having 
to write the code resources. ObjectDraw uses this routine for the 
LDEF that defines the tool palette. 


UDemoLDef .p ObjectDraw uses the List Manager (see Inside Macintosh IV, 
Chapter 30, “The List Manager Package”) to implement its tool 
palette. This file contains the code for the list definition function. 


UDemoObject .p This file is the workhorse of the ObjectDraw application. It con- 
tains all the objects and methods for drawing shapes in a window. 


UAbout Box.p Every application needs a nifty About... box. This file contains the 
code for ObjectDraw’s About... box. 


ObjectDraw/DA.p This file is the main program. It is a unit that defines a function 
main that THINK Pascal uses as the entry point of the desk ac- 
cessory. See Chapter 12 for details. 


Since you'll be testing the desk accessory before you actually build it, you need to add the 
DA Shell to your project. This source file is in the same folder as THINK Pascal. If you fol- 
lowed the installation instructions, it’s in a folder called THINK Pascal Folder. Add the DA 
Shell the same way you added all the other source files. 
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Your project window should look like this now: 


Options File (by build order) Size 
PRuntine lib 
Interface lib 
PrintCalls.lib 
MacPrint.p 
Objintf.p 
UDernoUtils.p 

UDP Install.p 
UDemoLDef.p 
UDemnoObjects.p 
UAboutBox.p 
ObjectDraw/DA.p 
DA Shell 


ooo00o00 00 0000 


R 
R 
R 
R 
R 
R 
R 
R 
R 


Setting the Compile Options 


If you went through the tutorial in the last chapter, you know that ObjectDraw DA uses con- 
ditional compilation so you can use the same source files for the ObjectDraw application and 
the ObjectDraw desk accessory. You need to define the compiler variables DeskAcc and 
DAProject to make sure that the compiler compiles the right code for the desk accessory 
version. 


Note: There’s nothing magic about these compiler variables. You don't have 
to write your desk accessories this way if you don’t want to. 
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Use the Compile Options... command. in the Project menu. to set the values of these two 
compiler variables: 


Compile Options 


Compile-Time Variables Code Generation 


THINK_PASCAL=TRUE; CL) Mc6ses 


Elems881=TRUE; O mc68020 
DeskAcc=TRUE; 


DAProject=TRUE; SET OF Integer 


@ 0..255 
© -32768 .. 32767? 


aa 


When the compiler variable DeskAcc is defined as true, THINK Pascal compiles the code 
that pertains to desk accessories. When the compiler variable DAProject is true, THIN 
Pascal compiles code that applies only when you’re testing the desk accessory. Later on, 

when you build the desk accessory, you'll set the value of this compiler variable to false. 
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Setting the Run Options 


Now you have to make sure that the project knows where its resources are. Choose the Run 
Options... command in the Run menu. You'll see this dialog box: 


Run-time Environment Settings 


(] Use resource file: 
for resources used by the project. 


Text Window saves [5000 |characters 


CJ Echo to the printer 


Resources 


Hello world. » = 811.79. 
Monaco ma 


Stack size:| [| kilobytes 
Zone size:|256 |kilobytes Cancel | 


Memory 


59 


THINK’s Lightspeed Pascal 


Click on the Use resource file: check box. You'll see a standard file dialog. Select Ob- 
jectDraw/DA.Rsrc and click on the Use button. 


© ObjectDraw Folder 


& ObjectDraw 

D ObjectDraw DA 

DO ObjectDraw.n 

D ObjectDraw.Rsrc 

QD ObjectDraw/DA Build.w 
O ObjectDraw/DA.n 


OD ObjectDraw/DA.Rsre (Use } 


Stack size:[16__ kilobytes j 
Zone size:[128 |kilobytes i 


Memory 


The resource file ObjectDraw/DA.Rsrc was created with ResEdit. You can use ResEdit to 
look at or change some of the resources. 


Note: A RESOURCE FILE USED BY A PROJECT MUST BE IN THE SAME 
FOLDER AS THE PROJECT. 


Segmenting the Project 


If you try to compile the project now, THINK Pascal will give you an error message that says 
that a code segment is larger than 32K. Macintosh programs are made up of one or more 
CODE resources that contains the machine language code of your program. The Macintosh 
operating system takes care of loading these CODE resources when you need them. The only 
thing you have to worry about is making sure that they’re smaller than 32K. When THINK 


Pascal reports that a segment is larger than 32K, you need to break up your program into 
more segments. 
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Click on the “Towers of Hanoi” icon just above the up-arrow on the right of your project 
window. The project window display changes so it looks like this: 


PRuntirne Jib 
Interface lib 
PrintCalls.lib 
MacPrint.p 
Objintf.p 
UDbemoUtils.p 
UDP Install.p 


UDernoLDef.p 
UDermoObjects.p 
UAboutBox.p 
ObjectDraw/DA.p 
DA Shell 

sone SEE F 


AARAAAAADAA 


Click on the last file in the project, DA Shell, and drag it below the line that says Segment 1. 
Your project window should look like this now: 


piRuntinne lib 
Interface lib 
PrintCalls.lib 
MacFrint.p 
Objintf.p 
UDermoUtils.p 
UDP Install.p 
UDeroLDef.p 
UbernoObjects.p 
UAboutBox.p 
ObjectDraw /DA.p 
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Now your program has two segments. Click in the icon in the upper right corner of the win- 
dow again to go back to the original view of your project: 


== ObjectDraw DA. 


Options File (by build order) Size 
ptRuntime.lib 
Interface lib 
PrintCalls.lib 
MacPrint.p 
Objintf.p 
UDemoUtils.p 
UDP Install.p 
UDemoLDef.p 
UDemoObjects.p 
UAboutBox.p 
ObjectDraw /DA.p 
DA Shell 


ooo0o000c0c0c00 000 


R 
R 
R 
R 
R 
R 
R 
R 
R 


The normal view you're used to by now is called the Build Order view because it lists the 
files in the order that THINK Pascal compiles them. The other view is called the Segment 
view because it shows how your program is broken up in different segments. 


Note: To learn more about segmentation, see Chapter 7. 
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Running the Project 


Now you're ready to run the project. Choose Go from the Run menu. THINK Pascal loads all 
the libraries and compiles all the source files. When it finishes compiling, THINK Pascal 
launches the DA Shell. To use your desk accessory, choose the Sample DA command from 
the Apple menu. The DA Shell starts your program and feeds it events so it looks like it’s a 
desk accessory. 


Object Draw D 


If you like, you can click on the bug spray can in the far right of the menu bar to halt the pro- 
gram so you can use THINK Pascal’s debugging tools. 


To go back to THINK Pascal, choose Quit from the DA Shell’s File menu. 


Building the Desk Accessory 


Once you're sure that the ObjectDraw application runs correctly, build it as a desk accessory 
that you can add to your system with the Font/DA Mover. Choose the Set Project Type... 
command in the Project menu and click on the Desk Accessory icon. 


In the Resource Information name box, type in the name you want to give your desk ac- 
cessory. This is the name that will appear in the Apple menu when you install your desk ac- 
cessory with the Font/DA Mover. Now, check the Multi-Segment check box in the Driver 
Information section. 


Note: Whenever you use Object Pascal in a desk accessory, you have to 


check the Multi-Segment check box, even if the desk accessory has only one 
segment. 
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Your dialog box should look like this: 


r— File Information 
Type: |DFIL Creator: (Bundle Bit 


-— Resource Information 


Name:|ObjectDraw DA 


OO custom Keader 


Application 


Attributes: 


r— Driver Information 


Code Resource 


The Type and Creator values let the Finder know that the final file is a desk accessory, so it'll 
be displayed with the suitcase icon. The resource type DRVR lets the Macintosh know that it’s 


a desk accessory. 


When you’ve set all the fields, click on the OK button. 
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Remember the compiler variables that control how your source files are compiled? You need 
to change one of them, DAProject, when you compile your program as a stand-alone desk 
accessory. Choose the Compile Options... command in the Project menu to change this 
compiler variable: 


Compile Options 


Compile-Time Variables Code Generation 


THINK_PASCAL=TRUE; CL Mc688s81 


Elems881=TRUE; CJ Mc68020 
DeskAcc=TRUE; 


DAProject=FALSE; SET OF Integer 


@ 0..255 
© -32768 .. 3276? 


Cancel 


Now replace WRuntime.1ib with DRVRRuntime.1ib. Hold down the Option key as you 
double-click on KRuntime.1ib in your project window, When THINK Pascal displays the 
standard file dialog, move to the Libraries folder, and double-click on DRVRRuntime. lib. 


Next remove the DA Shell source file from your project. Select the DA Shell file in the project 
window and choose Remove from the Project menu. This command lets you take source 
files and libraries out of your project. 
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Finally, choose the Build Desk Accessory... command from the Project menu. THINK 
Pascal will ask you to name the suitcase file for your desk accessory. Be sure you move to the 
ObjectDraw Folder before you click on the Save button. 


© ObjectDraw Folder 


& Gh jec Wrauws 
fy G8 je (Brads OR 
Objec Mraw BR 
 Objectiraws 
Y OBjec Oraus.p 
Ob jec raw Rsr¢ 


Save Desk Accessory as 


ObjectDraw DA 


& Smart Link 


When the Smart Link check box is checked, THINK Pascal strips out any code you don’t use 
to makes sure that the desk accessory is as small as possible. 


In the ObjectDraw Folder you'll see the suitcase file that contains your ObjectDraw desk 
accessory. You can use the Font/DA Mover to install the desk accessory into your System file. 


In this tutorial, you used the same project for testing your desk accessory with the DA Shell 
and for building your desk accessory. In this case, it’s OK to work this way because you 
were working with files someone else wrote for you. In actual practice, you'll find it more 
useful to create two different projects: one that contains the DA Shell for testing, and another 
that has all the project type and compile options set up for building. 


Where to Go Next 


If you want to learn more about writing desk accessories, read Chapter 12, Inside Macintosh 
J, Chapter 14, “The Desk Manager,” and Inside Macintosh II, Chapter 6, “The Device 
Manager.” 


The chapters in the following section show you how to use the different parts of THINK 
Pascal. You can read them in order, or you can skip around to the parts you’re particularly 
intested in, 


THINK’s 


Lightspeed Pascal 


PART THREE 


Using THINK Pascal 


6 Editing 
7 Working with Projects 
8 Running Programs 
9 Debugging Programs 
10 Units and Libraries 
11 Using Predefined Routines 
12 Building Projects 
13 Assembly Language 
14 LightsBug 
15 Compiler Directives 


Editing 
6 


Introduction 


THINK'’s Lightspeed Pascal contains an integrated text editor that’s specifically designed to 
help you write Pascal programs. The THINK Pascal editor uses standard Macintosh editing 
techniques, so you'll have no trouble getting started. 


The THINK Pascal editor is designed to work on Pascal source files. The editor formats — 
pretty-prints — your program and highlights lines that contain syntax errors. If you try to edit 
an ordinary text file, the editor will try to format it as a Pascal program, which is not what you 
want at all. (You may want to try it once, just to satisfy your curiosity.) 


You can use any text editor you like to create your Pascal source file. Just be sure that you 
save your Pascal file as text only. Since the file is presumably a Pascal program, the ‘THINK 
Pascal editor will be able to read it. 


Topics covered in this chapter 
e Creating and opening files 
¢ Working with windows 
¢ Editing files 
¢ Searching and replacing 
¢ Printing files 
* Closing and saving files 
* Customizing program formatting 


Creating and Opening Files 


The THINK Pascal editor lets you edit up to eight files at once. Each file appears in its own 
edit window. 


Creating a new file 


To create a new file, choose New from the File menu. An untitled edit window will appear, 
ready for you to start typing. You can save, edit, and check the syntax of the file, but you 
can’t compile it until you add it to a project. 


Opening an existing file 


To open an existing file, choose Open... from the File menu. A standard file dialog lets you 
select the file to open. 
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Note: Before you can compile a file, it must be in a project. To learn about 
projects and how to add source files to them, see Chapter 7. 


To open a file that’s already in a project, just double-click on its name in the project window 
to open it. If the file is already open, double-clicking brings the file’s edit window to the 
front. 


Opening a unit 


If you're working on a file that’s already been compiled, you can use a shortcut to open any 
unit that it uses. Hold down the Option key as you click in the title bar, and you'll see a pop- 
up menu that contains the names of all the units used by the file you’re working on. 


Editor TopLeve 


EditorGlobals 
ShowEdit 
ChangeFont 
{ EditorUtilities 
{ Modification History : 
8/19/86 RwH commented out line that enables ‘Print’, Added OTHERWIS 


case stmt in DoEdit. Added cases for PageSetup, Print in 
d otherwi: i id} a] 


unit EditorTopLevel; 


interface 


uses 
EditorGlobals, ShowEdit , ChangeFont, EditorUtilities; 


When you choose one of the names in the pop-up menu, THINK Pascal opens the file that 
contains that unit. 


Working with Windows 


THINK Pascal uses the edit windows for more than editing. During compilation or execution, 
it uses these windows to show diagnostic information. When your program is running, you 
can use the windows for source level debugging. (To learn more about debugging, see 
Chapter 9.) 


When you open a source file while you’re program is running, THINK Pascal scans it to col- 
lect information about the code. THINK Pascal displays a dialog box to let you know it’s 
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checking your file. Because it takes a little time to collect this information, THINK Pascal can 
keep the file open even though the window is closed. 


When you click on an edit window's close box, THINK Pascal just bides the window. The file 
associated with the window is still open. If you hold down the Option key as you click in the 
close box, THINK Pascal hides all the visible windows. 


To show a window that you’ve hidden, you can select its name from the Windows menu or 
double-click on its name in the project window. 


Note: To close a file, hold down the Command key as you click in the win- 
dow’s close box. You can also use the Close command in the File menu if 
the window is the active window. See “Closing and Saving Files” below. 


Editing Files 


The THINK Pascal editor is designed specifically for editing Pascal programs, but all the stan- 
dard Macintosh editing techniques work the way you're used to. Cut, Copy, Paste, and 
Undo all work the way they do in other applications. 
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Typing text 

As you type your Pascal source code to an edit window, the THINK Pascal editor formats it 
— pretty-prints — automatically. This means that Pascal reserved words (like program, 
begin, and end) may appear in bold face and that certain lines are indented. 


Bullseye.p 


program Bullseye; 
const 
Scale = 8; 
var 
hPos, ¥Pos: integer; 
Radius, i: integer ; 


begin 
hPos = 100; 
yPos = 100; 
PenModelpathor) ; 
for j := 10 downto 1 do 
begin 


Radius := i * Scale; 
PaintCircle(hPos, ¥Pos, Radius) 
end 
end. 


You can use the Source Options... command in the Edit menu to change the way THINK 
Pascal pretty-prints your code to suit your taste. See “Customizing Program Formatting” 
below. 


Note: While the Source Options... command lets you customize how the 
editor pretty-prints, you can’t disable pretty-printing altogether. 


If you uncheck the Auto-Reformat option in the Edit menu, THINK Pascal will stop pretty- 
printing your program on every line. Pressing the Enter key or clicking the mouse will pretty- 
print everything you've typed so far. 


Syntax errors 

‘The editor checks the syntax of your Pascal program as you type it in. THINK Pascal checks 
the syntax of your program when you type a semicolon, press Enter, press Return, or click on 
another line in your program. 


If the editor detects a syntax error, it displays the rest of the line in outline style. In the exam- 
ple below, there is an extra colon in front of the Pascal assignment operator, : =. 


Bullseye.p 


program Bullseye; 
const 
Scale = 8; 
var 
hPos, yPos: integer; 
Radius, i: integer; 
begin 
hPos = 100; 
yPos = 100; 
PenMode(patXor); 
for ij = 10 downto 1 do 
begin 
Radius: = ] @ Geale; 
PaintCircle(hPos, yPos, Radius) 
end 
end. 


Note: THINK Pascal doesn’t always identify syntax errors correctly. For ex- 
ample, if you omit a semicolon, the statement on the following line will be 
ouuined. But it’s usually obvious what caused the error. 


Once you correct the error, just go on editing. The outlining will disappear as soon as you 
press Return or Enter, or click on another line in the file. 


Undoing changes 


If you make an unintentional change to your file, use the Undo command in the Edit menu 
to correct it. Undo remembers only the last thing you did. You can also use Undo to redo 
what you undid. The wording of the Undo command always reflects what it will undo. For 
instance, if you cuta range of lines, the undo command will read Undo Cut. If you select 
Undo, the command will now say Redo Cut. Undo works on these commands: Cut, Clear, 
Paste, and Replace. You can also undo the last run of typing. 


Note: You can’t undo a Replace All command. (See “Searching and 
Replacing” below.) 
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If you’ve made a number of changes to your file, and you want to undo all of them, use the 
Revert command in the File menu. Revert discards all of the changes you’ve made since 
you last saved the file. 


Selecting words and lines 
To select a word, double-click on it. To select an entire line triple-click anywhere on the line. 


If you drag after double- or triple-clicking, the editor extends the selection by words or by 
lines. 


Scrolling to the insertion point 

The THINK Pascal editor lets you examine other areas of your source file, then jump back to 
where you were. Press the Enter key or choose the Show Selection command from the 
Search menu while you are anywhere in the file to make the editor scroll to the insertion 
point or to the beginning of the current selection. 


Moving back to an error 


If THINK Pascal discovers an error in your program, and the editing window containing the 
error is open, then that window will become the active window, and a “thumbs down” points 
to the line with the error. (This feature is described in more detail in Chapter 8.) 


If you scroll the window away from that point, you can use the Show Error command in the 
Search menu to get back to that point quickly. 


Using the arrow keys 


The arrow keys on the Macintosh Plus, Macintosh SE, and Macintosh II keyboards move the 
insertion point up, down, left, and right. You can use the Command and Option keys with 
the arrow keys to move to specific places in the file. 


Type this... To move the insertion point to... 
Command-Up Top of page 

Command-Down Bottom of page 

Command-Left Beginning of line 

Command-Right End of line 

Option-Up Beginning of preceding procedure or function 
Option-Down Beginning of next procedure or function 
Option-Left Beginning of previous token 
Option-Right Beginning of next token 
Command-Option-Up Beginning of file 
Command-Option-Down End of file 


You can hold down the Shift key as you press any of the arrow keys to extend the selection. 


If you’re using an Apple Extended Keyboard on a Macintosh SE or a Macintosh II, you can 
use the six key cluster. 


Type this... To do this... 

Home Scroll to the beginning of the file 
End Scroll to the end of the file 

Page Up Scroll up one windowfull 

Page Down Scroll down one windowfull 


Note: These keys just scroll in the edit window. They don’t move the inser- 
tion point. 


Moving to a procedure or function 

THINK Pascal gives you a quick way to move to any procedure or function in your source 
file. When you hold down the Command key and click in the title bar of an edit window, 
THINK Pascal displays a pop-up menu of all the procedures and functions defined in the file: 


Editor Utilities 


EditorUtilities 
HandleUpdate 
MyErrorflert 
SetEnable 
Num2Str 
ReadDeskScrap 
WriteDeskScrap 
UpdateClipBd 
DuplicateFile 
NewName 
DuplicateName 
StandardFile 
ReadFile 

ReadErr 

TestErr 
WriteFile 

TestErr 
AllocFile 
ChangeFile 
DeallocFile 
TestFront 
FixEditMenu 
AllFileBytes 
TopWindowBytes 

DrawDLine 

CenterDitem 

FrameDltem 

DoAbout 


hile writing to "', fName, '": 1/0 error *', Nui 
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When you choose a procedure or function name from the pop-up menu, the insertion point 
moves to the beginning of the routine. 


The names of the routines appear in their declaration order. If you hold down both the 
Command and Option keys as you click in the title bar of the edit window, the pop-up menu 
contains the routine names in alphabetical order. 


Searching and Replacing 


The THINK Pascal editor lets you search and replace strings in your Pascal source files. All of 
the searching and replacing commands are in the Search menu. The search and replace 
commands apply to Pascal edit windows, the Instant window, and the Observe window. 


Note: Earlier versions of ‘THINK Pascal used a different technique for 
searching and replacing. Be sure to read this section even if you’re an expe- 
rienced THINK Pascal user. 


Finding a string 
Use the Find.., command in the Search menu when you want to look for a string in the cur- 
rent window. You'll see this dialog box: 


Search for |HandleScroll 


Replace with | | 


@ Separate Words © All Occurrences 


@ Case Is Irrelevant ©Cases Must Match Don't Find 
OO Multi-File Search 


‘Type the string you're looking for in the Search for field, and click on the Find button. If the 
string is in the file you're editing, it will be highlighted. If it’s not, the editor just beeps. 


If you want to look for the next occurrence of the string, use the Find Again command. 


Another way to specify the search string is to use the Enter Selection command. This com- 
mand places the current selection (the highlighted text) in the.Search for field. Use the Find 
Again command to look for the string. 


Search options 


The four radio buttons in the Find... dialog let you specify how the editor looks for your 
string. If you click on the Separate Words button, the search will match only whole words. If 


you click on the All Occurrences button, the search will match even if your string is embed- 
ded in a longer string. 


If the Case is Irrelevant button is on, the search treats uppercase and lowercase letters as if 
they were the same. If the Cases Must Match button is on, the search will match only if the 
string matches exactly. 


Note: Searching with the Separate Words button on is usually faster than 
searching with the All Occurrences button on, 


The THINK Pascal editor searches forward and stops when it finds a match or when it 
reaches the end of the file. 


Setting things up for searching later 

In addition to the Find button (“Go ahead with the search”) and the Cancel button (“Pretend 1 
never invoked this command”), there is a Don’t Find button. Clicking on this button sets up 
the search and replacement strings without actually doing the search. 


You might wantto use this button when you realize that the insertion point is not where it 
should be to start the search. Click on the Don’t Find button, move the insertion point to the 
proper place, then use the Find Again command to look for your string. 


Replacing a string 

If you want to replace some but not all instances of the search string, type a replacement 
string in the Replace with field of the Find... dialog. Then, when the editor finds the first oc- 
currence of the string, you can use one of the commands in the Search menu to replace it. 


Use this command... To do this... 

Replace Replace the current selection with the replacement 
string without looking for the next occurrence of the 
search string. 


Replace and Find Again Replace the current selection with the replacement 
string and then look for the next occurrence of the 
search string. 


Find Again Look for the next occurrence of the search string with- 
out replacing anything. 


Replace All To replace all occurrences of the search string with the 
replacement string. The editor replaces from the cur- 
rent insertion point to the end of the file. 
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Searching in more than one file 

The Mullti-File Search option in the Find... dialog lets you look for a string in all the files of 
your project. Just check the option and click on the Find button. THINK Pascal searches each 
file in your project until it finds your string or until it runs out of files. 


When the editor finds the string, it opens the file the string is in. At this point, you can use the 
commands in the Search menu to look for the next occurrence of the string in the file. When 
you're ready to look in other files, use the Find in Next File command. 


Note: Multi-File search just finds the first instance of the search string in 
each file. To find subsequent instances of the string in the file, use the Find 
Again command. Once you choose the Find in Next File command, THINK 
Pascal will look in the next file even if there are more instances of the search 
string in the current file. 


Printing Files 


Use the Print... command in the File menu to print the file in the active window. You'll see 
the standard printing dialog for the printer you're using, 


Note: You can print the contents of the project window, the Observe win- 
dow, and the Instant window as well as any edit window. 


The File menu also has a standard Page Setup... command that lets you set up the page size 
and other options before you print. 


Closing and Saving Files 


It's a good idea to save your work every fifteen minutes or so, just in case something horrible 
happens. Power failures usually come at the most inopportune times, and inexplicable 
crashes do occur. 


Closing a file 


To close a file, its window must be the active window. Choose Close from the File menu. If 
you’ve made any changes to the file, THINK Pascal will ask you whether you want to save 
the changes. 


Another way to close a file is to hold down the Command key as you click in its window's 
close box. To close all the open files, hold down the Option and Command keys as you click 
in the close box. 


Note: Unlike other Macintosh applications, clicking on an edit window’s 
close box does not close the file, it just hides the window. You must use the 


Close command in the File menu or hold down the Command key as you 
click on the close box. 


Saving a file 

To save a file without closing it, use the Save command in the File menu. If you’ve never 
saved the file before, this command will be dimmed, and you'll need to use the Save As... 
command to save it. 


Saving a file with a different name 

The THINK Pascal editor gives you two ways of saving a file under a different name. The 
Save As... command asks you for the new name and then saves the contents of the edit win- 
dow with that name. If the file is part of the current project (it’s in the project window), its 
name will change there, too. If the project already has a file with the new name, you'll be 
asked for another name. You can’t overwrite an existing project or library file. You have to 
delete it first. 


When you choose the Save As... command, you'll see a standard save dialog box with two 
additional radio buttons. When you choose Text Only, THINK Pascal saves the file as a text 
file that you can open with any text editor or word processor. When you choose Entire 
Document, THINK Pascal saves the file in a special format that loads faster and preserves any 
Stop signs you’ve set in the file. 


G TextEd Demo 


Change Foa? 
Editor biobats 
Editor iat 
Editor Main 
Editor Project 


Editor Teptevel 


Save ‘Bullseye.p' as 


Editor Extras 


@ Text Only 
© Entire Document 


The Save a Copy As... command does not affect the project or the editing window. It simply 
“snapshots” the contents of the file in the window to another file. This is a good way to make 
backup copies without mistakenly editing the backup. The original file remains in the active 
editing window and the project remains unchanged. 
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Save options 

Whenever you save a file, you can save it as Text Only or as an Entire Document. The option 
you choose depends on how you want to use the file. Files saved as “Text” are smaller, and 
you can edit them with other editors, but they take longer to load into THINK Pascal. Files 
saved as “Entire Document” preserve Stop Signs (described in Chapter 9) in the file, and load 
faster, but they take up more space on your disk. 


Customizing Program Formatting 


The Source Options... command in the Edit menu lets you change the way the THINK 
Pascal editor pretty-prints your source code. You can also change the tab spacing, the inden- 
tation spacing, and the font the editor uses to display your file. 


There are about eleventy-zillion ways to format a Pascal program. While the options in this 
dialog box won't satisfy every Pascal programmer, you can set some of your preferences with 
this command. 


When you select the Source Options... command, you'll see a dialog box like this: 


Source Display Settings 


[eneve 7 


program test; 
var 
i, sum: integer ; 
Keywords |begin 
surn = O; {initialize to zero} 
fori 1 to 10do 


Suri := suri + i; 
end writelnC'sum = ', sum); 


Indentation |end. 


Ca; bye) 
C3; 
t) 


Parameters OK J Save Settings 


80 


The four icons along the left let you choose different aspects of the formatting you can 
change with this command. When you click on the OK button, any changes you made in any 
section of this dialog will apply to your project. Clicking on the Save Settings button saves the 
settings as the THINK Pascal defaults. 


Changing the font 


To change the font, click on the Fonts icon in the dialog box. At the top of the box you'll see 
two pop-up menus: one for the font, another for the size. The sample program in the middle 
of the dialog box lets you see what the different fonts and sizes look like. 


Changing the appearance of keywords 

The Keywords section lets you change the way Pascal reserved words appear in the edit 
window. The three radio buttons on the left control the case of the words, and the three radio 
buttons on the right control the style. 


Source Display Settings 


@ Lowercase @® Boldfaced 
© Uppercase © Underlined 
© Mixedcase © Plain Text 


Cabye) 
C3; 


pareinetete OK Save Settings 


The most common keyword styles are lowercase bold, uppercase plain, and lowercase 
underline. 
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Changing the indentation 
The Indentation icon lets you change how the THINK Pascal editor indents your program. 


Source Display Settings 


{X] BEGIN starts a new line 
Indent BEGIN/END within statements 
f& Indent statements within BEGIN/END 


Key words 
( Outdent declarations 


Indent: Pe | spaces 
Indentation 


Tabs at: [5 | spaces 
Ke 
Parameters Save Settings 


“BEGIN starts a new line” means that the reserved word begin will appear at the beginning of 
a new line. When this option is off, begin appears at the end of a line. This is what your code 
looks like when you don’t check this option: 


2 
2! 


d 


while i <> 0 do begin 
end; 


“Indent BEGIN/END within statements” means that begin/end pairs will be indented like this: 


for i := 1 to 10 do 
begin 


end; 
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If this option is not checked, the code fragment would look like this: 


for i := 1 to 10 do 

begin 

end; 

“Indent statements within BEGIN/END” controls whether statements within a begin/end pair 


are indented or lined up with the begin/end pair. Here’s what code looks like when this 
option is checked: 


for i := 1 to 10 do { BEGIN starts a new line is on } 
begin { Indent BEGIN/END within statements is on } 
if Search(theWorldOver, trueLove) then 
Gazelle; 
{ more statements } 
end; 


“Outdent declarations” controls whether the const, type, and var declarations in program, 
procedure, or function declarations should be indented or lined up with the begin/end 
pair. This is what outdented declarations look like: 


program Outdent; 


procedure Delicate; 
var 
aVar : aType; 
begin 
end; 


begin 
end. 


And this is what code looks like with outdented declarations off: 


program NoOutdent; 


procedure Delicate; 
var 
aVar : aType; 
begin 
end; 


begin 
end. 
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Changing the parameter list format 

Some people like to see all the formal parameters to functions and procedures on the same 
line. Other people like to see each parameter on a line by itself. The radio buttons in the 
Parameter section of the Source Options... dialog let you choose the format you like best. 


Source Display Settings 


@ List formal parameters horizontally 


© List formal parameters vertically 
Key words 


end 


Indentation 


(ajb;e) 


Ca; 
b 
[ OK Save Settings Cancel 
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Introduction 


This chapter describes projects, the structure that is at the heart of the THINK’s Lightspeed 
Pascal development environment. The first section tells you what a project is all about, and 
how it relates to traditional development environments. The next section describes units, or 
program modules, and shows you how to add source files to a project. Then you'll learn how 
to arrange files within a project. The last section shows you how to change the way the pro- 
ject window looks. 


What you should know 

You should know how to use the THINK Pascal editor. You use the editor to create and edit 
the source files that eventually become a part of your projects. The preceding chapter tells 
you all about the THINK Pascal editor. 


Topics covered in this chapter 
e What is a project? 
e The project window 
* Creating a new project 
* Opening an existing project 
¢ Closing projects 
e Adding files to projects 
e Arranging files in the project 
e Setting the compiler options 
° Customizing the project window 


What Is a Project? 


Most Pascal programs consist of several source files and libraries, A small program might be 
made up of one or two source files. A large, full-featured program, though, usually consists of 
two or three dozen source files and libraries. In traditional development environments, you 
create and edit your source files with a text editor. Then the compiler generates an object file 
from the source files. Finally, when you have all your object files together, the linker links all 
the object files and libraries to produce an executable application. As your program gets 
larger, it gets harder to keep track of which files need to be recompiled because you've 
edited them, And once you've compiled the changed files, you still have to link all the object 
files together. 
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Because THINK Pascal is an integrated environment, the editor, compiler, and linker are all 
part of the same application. When you edit a source file with the THINK Pascal editor, the 
compiler knows that it will need to recompile that file. As the compiler generates object code 
for your source file, it also generates information for the linker, so it can link in a flash. The 
thing that holds all the pieces together is the project. 


The project is at the heart of the THINK’s Lightspeed Pascal development environment. It 
takes over the functions of several other files in more traditional development environments. 
The project holds the object code of all your compiled source files and maintains the depen- 
dencies between them. It keeps track of files that need to be recompiled because you’ve 
edited them with the editor. The project also keeps track of information used by the source 
level debugger. 


The Project Window 


The project window displays information about each file in your program. To tell THINK 
Pascal that a file is part of your program, you add it to your project, and the file name appears 
in the project window. 


Usually, you’ll see the name of the file, the compiler options for the file, and the size of the 
file’s object code. (The last section in this chapter shows you how to change the way THINK 
Pascal displays information in the project window.) 


This is the project window for the Text Editor on disk THINK Pascal 2 of your THINK 
Pascal package. 


>> Editor Project =] 


Options File (by build order) Size 
Interface lib 
Runtime lib 
[JIE] Editor Globals 
[VIE] Editor Init 


[IIR] Show Edit 
Change Font 
[R] Editor Utilities 


ooo0oo0o0o00090 


The window shows you the compiler options for each file, the name of the file, and the size 
of the object code. In the picture above, none of the files have been compiled, so the size 
column shows zeros for all files. 
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Ignore the Options column for the moment. The section “Changing Compiler Options” below 
tells you more about compiler options. 


The File column shows you the name of the files in your project. If you double-click on a file 
name, THINK Pascal opens an edit window for it. You can click on a file name to select it, 
and drag its name to a different place in the project window. The section “Arranging Files in 
the Project” tells you why you would want to drag file names around. 


The Size column shows you the size of the files’ object code in bytes. When you add a new 
file to a project, the object size is zero because it hasn’t been compiled yet. When a file is 
compiled, its size appears in the Size column, Unlike other development environments, 
THINK Pascal doesn’t generate separate object files for each source file. Instead, THINK 
Pascal stores the object code in the project document. 


Creating a New Project 


To create a new project, use the New Project... command in the Project menu. You'll see a 
standard file dialog asking you to name the project. By convention, project names end in ei- 
ther the word “project” or with a “.n” suffix. You don’t have to name your projects this way. 


Note: To make a “n”, type Option-p. 


THINK Pascal creates a new project document and displays a project window like this: 


Options File (by build order) Size 


Runtime.lib 
Interface lib 


New project windows have two libraries, Interface.1lib and Runtime.1ib, added 
automatically. Interface.1ib contains code for using the Macintosh Toolbox from THINK 
Pascal. Runtime. 1ib contains the standard predefined routines like writeln. Nearly ev- 
ery Pascal program you write on the Macintosh requires both of these libraries. Chapter 11 
describes these libraries in detail. 


Opening an Existing Project 


To open an existing project, you can double-click on its icon from the Finder, or you can use 
the Open Project... command in the Project menu. If you already have a project document 
open, you have to close it before you can open another project. 
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Closing Projects 


Use the Close Project command in the Project menu to close the project document. THINK 
Pascal closes any open source files that are part of the project. If you've edited a file, and you 
haven’t saved it, THINK Pascal will ask if you want to save the changes before closing the 
project document. 


When you click in the project window's close box, THINK Pascal just hides the window, It 
doesn’t close the project. 


Note: If you hold down the Command key as you click in the project win- 
dow’s close box, THINK Pascal will close the project. 


After you close a project, THINK Pascal displays a standard file dialog that lets you open an- 
other project. If you don’t want to open a project, just click on the Cancel button. 


Adding Files to Projects 


THINK Pascal gives you two ways to add files to a project. If you're editing a file that isn’tin 
the project window, you can use the Add Window command in the Project menu to add 
the file in the current edit window to the project. If it’s a new file, THINK Pascal will ask you 
to save the file first. 


To add a file on disk to your project, use the Add File... command in the Project menu. This 
command displays a standard file dialog. Select the file you want to add, and click on the 
Add... button. After THINK Pascal adds the file to the project, it lets you choose another file 
to add. When you're done adding files, click on the Done button. 


You can add four kinds of files to your project: 
¢ THINK Pascal source files 
¢ THINK Pascal libraries 
¢ THINK’s LightspeedC libraries 
¢ Macintosh Programmer's Workshop object files (. 0 files) 


When you add a new file to a project, THINK Pascal puts it at the end of the list. Usually, 
you'll need to move the file to a different position in the build order so your program com- 
piles correctly. The next section shows you how to use the project window to order your 
files. 


To remove a file from a project, select a file in the project window and choose the Remove 
command from the Project menu. This command just removes the file from the project. It 
doesn’t delete the file from your disk, so if you remove a file accidentally, you can just add it 
back. 
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Note: When you want to replace one file with another, hold down the 
Option key and double-click on the name of the file you want to replace. 
THINK Pascal will let you pick a replacement file. This shortcut is the same 
as doing a Remove and then an Add File.... 


Arranging Files in the Project 


There are two ways you can arrange the files in the project window: by build order, and by 
segment. The build order determines the order that THINK Pascal compiles your files. The 
segment view lets you specify how THINK Pascal segments your code. To see the different 
views, click on the view control icon in the upper right of the project window to choose the 
view you want. 


Changing the build order 

In a Pascal program you can’t use a variable or a subroutine unless it has been defined first, 
so the order that THINK Pascal compiles your files is important. When you view your project 
by build order, your main program will always be the last file in the list. 


To change the position of a file in the build order, just click on the file and drag it to the 
proper position. If a file is in the wrong order, THINK Pascal lets you know by telling you 
that some variable or subroutine hasn’t been defined yet. 


Segmentation 

Most Macintosh applications are made up of several segments. Segments are collections of 
code that the operating system moves in and out of memory. The Macintosh limits segments 
to 32K, so if you’re writing a large program, you will have to segment your code. To learn 
more about segments, read Inside Macintosh Il, Chapter 2, “The Segment Loader.” 


Note: Segments correspond loosely to overlays in other development envi- 
ronments. 


THINK Pascal lets you segment not only applications but desk accessories and device drivers 


as well. An application can have up to 127 segments. Desk accessories and device drivers can 
have up to 31 segments. 
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Dotted lines separate segments, and the number of the segment appears after the last file in 
the segment. This is the segment view of the Editor project. 


=> Editor Project > 

Options File (by segment) Size 
Interface .lib 8104 
Runtime.lib 


ee Editor Globals 
Show Edit 


ARE Editor ia 


To create a new segment, drag a file into the space just below the last file in the window. To 
add a file to an existing segment, just drag the file name into the segment. Any segments that 
become empty are automatically deleted. 


At the end of each segment is the maximum number of total bytes of code in that segment. 


The two project views are completely independent. If you change the build order, the seg- 
mentation does not change. If you change the segmentation, the build order stays the same. 


Setting the Compiler Options 


The Options column in the project window displays the state of the debugging options for 
each file in the project. Enabling or disabling these options affects the code the compiler 
generates. Chapter 15 goes into detail about the compiler options. This section gives you a 
brief overview. 
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Option Meaning 

D Debug. Generates additional information between each 
Pascal statement to support stepping, stopping, and 
observing. 

N Names. Inserts the name of all routines (truncated to 


eight characters) into the code. This is useful for debug- 
ging with LightsBug and Macsbug. 


Vv Overflow Checking. Generates code that checks for in- 
teger arithmetic overflows. 
R Range Checking. Generates code that does range 


checking for array indexing, assignments, and parame- 
ter passing. It also generates code that checks for nil 
pointer dereferencing. 


A box around the letter means that the option is enabled. By default, the D and N options are 
on. To turn the options on and off, click on the option letters. 


Note: It’s a good idea to turn the V and the R options on while you're de- 
bugging your program. 


If you hold down the Option or Command key when changing an option, the new state of 
that option applies to all the files in the project. 


Here’s an example of a project window with some of the options turned off: 


=> editor Project => 
Options File (by build order) Size Al 
Inter face.lib 8104 LA 

7 Runtime.lib 13298 

¥ [RJ] Editor Globals Oo 

[]R Editor Init 1266 


[VIR] Show Edit 1000 
[RF] Change Font 1932 
[R] Editor Utilities 5736 

[J[R] Editor TopLevel 8342 

[¥J[R] Editor Main 76 
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Customizing the Project Window 


The View Options... command in the Project menu lets you customize what appears in the 
project window, When you choose this command, you see a dialog box like this: 


Project View Settings 


Options File (by build order) Size 
[DJIN) v [R] MemHacks 


[MIMI] Extremely w-i-d-e... 


& filename Dunit name Geneva J 9 ] 


& options (J volume name 
code size [date file saved 


OK 1 
File Information (_ 0k} (Lance 


Options - Boxed indicates enabled 
0 - Debug. Allows stepping, stopping, stack checking, Observing. 
N- Names. Insert Macsbug names into the code. 
U - Integer arithmetic overflow checking. 
R - Range checking. 


The two pop-up menus let you choose the font THINK Pascal uses to display the file names 
in the project window. The check boxes let you choose the information that appears for each 
file. The box at the top of the dialog box shows you what the project window would look 
like with the current settings. 


Option Meaning 

filename Displays the name of the file. 

options Displays the compiler options. 

code size Displays the size of the compiled code. 

unit name Displays the name of the unit. The unit name appears 
only after the file has been compiled. 

volume name Displays the volume or folder the file is in. 

date file saved Displays the last date and time you saved the file within 


the THINK Pascal environment. 
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The order that you click the check boxes determines the order of the display. In this exam- 


ple, the check boxes checked were filename, code size, date file saved, and options: 


Project View Settings 


File (by build order) Size Date Saved Options 
MemHacks 32767 12/27/85 10:43 [DIN V [RI 
Extremely w-i-d-e... 10 01/02/86 23:07 [BNI 


{&] options (volume name 
code size [date file saved 


File Information 


Options - Boxed indicates enabled 
D - Debug. Allows stepping, stopping, stack checking, Observing. 
N- Names. Insert Macsbug names into the code. 
U - Integer arithmetic overflow checking. 
R - Range checking. 


Gitilename Chunit name [Geneva] [3] 
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Running Programs 


Introduction 


This chapter shows you how to run a program in THINK Pascal. It tells you how THINK 
Pascal decides which files need to be recompiled, and what happens if there’s an error in 
your program, 


What you should know 


To run a program in THINK Pascal, you need a project document. If you don’t know about 
projects, read the preceding chapter. If you want to experiment as you read this chapter, use 
one of the projects included in your THINK Pascal package or one that you created from the 
tutorials. 


Topics covered in this chapter 
¢ Running a program 
« When something goes wrong 
¢ Stopping your program 
¢ Compiling, building, and linking without running 
* Save options 
e Run options 


Running a Program 


To run a program, just choose Go from the Run menu. You'll use the other execution com- 
mands — Go-Go, Step, and Trace — when you debug your program. In the next chapter, 
you'll learn how to use these commands. 


When you choose one of the commands in the Run menu, THINK Pascal examines your 
project to see which files need to be recompiled and relinked. If you’ve edited any source 
files or if you've added new source files to the project, THINK Pascal marks them for compi- 
lation. If you change the interface part of a unit, THINK Pascal marks all the files that use that 
unit. After marking the files, THINK Pascal compiles them by build order. 


Next, THINK Pascal links your program. It resolves references between files, and makes sure 
that names are not missing or defined more than once. 
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If there are any files that have changed, THINK Pascal asks you if you'd like to save them be- 
fore running the program. You can use the save options discussed below to tell THINK 
Pascal to always save your files before running or to never save your files before running. 


When the program starts running, your program’s menu bar replaces the THINK Pascal menu 
bar, and a bug spray can appears on the right side of the menu bar. You'll use the bug spray 
can to stop your program when you’re debugging it. 


When Something Goes Wrong 


If something goes wrong while THINK Pascal is compiling or linking your program, or if 
there is an error in your code, you'll see a bug box telling you what went wrong. Here’s an 
example of a bug box: 


Too many parameters used in procedure or function call. 


To get rid of the bug box, click the mouse or press the Enter or Return key. Of course, you 
still need to fix the bug! 


If your program has an error in it, THINK Pascal points out the error with a “thumbs down” 
next to the offending line in the file’s editing window. 


bullseye.p 


program Bullseye; 
const 
scale = 8; 
yar 
hPos, yPos: integer; 
Radius, i: integer; 
begin 
ShowDrawing; 
hPos = 100; 


yPos = 100; 
PenMode(patXor, 1); 
for i = 10 downto 1 do 
begin 
Radius = i * Scale; 
PaintCircle(hPos, vPos, Radius) 
end 
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If the error happens while your program is running, and the offending file’s editing window 
is open, THINK Pascal shows you the error the same way. 


If THINK Pascal finds a problem while it’s linking all the files in your project, it displays the 
message “Link Failed” and it shows you a Link Errors window. The messages in the Link 
Errors window tell you the names of undefined routines or the names of routines you’ve de- 
fined more than once. 


Link Errors 
undefined: "MISSINGPROCEDURE” 


If you want to know in which files THINK Pascal found the errors, use the Check Link 
command in the Run menu. When you use this command,. THINK Pascal reports the file 
names as well as the link errors. 


If the error happens while your program's running and the file’s edit window is not open, the 
thumbs down will appear in the project window, next to the name of the appropriate file. 


Bullseye. 


Options File (by build order) Size Al 
Runtime.lib 13298 [sy 


Interface.lib 8104 


(PIMIME] Bultseye.p 


Appendix E contains a list of error messages you might see when your program is compiling, 
linking, or running. 


Stopping Your Program 


To stop your program while it’s running, click on the bug spray can in the far right of the 
menu bar. Your program's menu bar disappears, and THINK Pascal’s menu bar and windows 
come to the front so you can look at what your code is doing. You can also type Command- 
Shift-Period to stop your program. 
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Note: You can stop your program only when it’s running code that was 
compiled with the Debug option on. If your program is running code that 
was compiled with the Debug option off, it will stop at the first place that 
was compiled with the option on. 


If the file your program stops in has an open edit window, THINK Pascal points to the state- 
ment you're stopped at. 


Editor Utilities 


where: Point; 
reply: SFReply ; 
textType: SFTypeList; 
begin 
where.h := 80; 
where.y := 55; 
textType[O] := fType; 
if opCode = StandardGet then 
SFGetFile(where, Null, nil, 1, textType, nil, reply) 
else 
SFPutFile(where, Null, oldName, nil, reply); 
with reply do 
if not good then 
StandardFile := Null 
else begin 
StandardFile := flame; 
yRef = vRefNurn 


} 
ead a file specified by the user into a handled buffer. The resu Ko] 
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If the file your program stopped in does not have an open edit window, THINK Pascal points 
to the file in the project window. 


Editor Project 


Options File (by build order) Size 
Interface.lib 8104 


Runtime.1ib 13298 

[R] Editor Globals a 
[R] Editor Init 1266 
[VIR] Show Edit 1000 
[R] Change Font 1932 
[R] Editor Utilities 5736 
[¥J[R] Editor TopLevel 8342 
[R] Editor Main 76 


f 


Dp) 
| 
1) (Ca 
(OIL) 
(DIN) 
[Dl 
a] 


To continue execution, choose any of the execution commands — Go, Go-Go, Step, or 
Trace — from the Run menu. To restart the program from the beginning, choose Reset from 
the Run menu before choosing Go. 


Note: THINK Pascal does an automatic reset when you edit any file in your 
project, when you change the project view, when you change the compile 
options, or when you rearrange the order of files in the project. 


Compiling, Building, and Linking Without Running 


You can compile your program without running it. You might want to make sure that a file 
compiles properly, or that you called all the procedures with the right number of arguments, 
or that you didn’t forget to define a procedure or function. 


To check the syntax of the file in the active edit window, use the Check command. This is a 
quick way to make sure your Pascal syntax is correct. To recompile the file, hold down the 
Shift key as you choose the Check command.. 


To compile all the marked files, use the Build command. This command looks through your 
project to see which files have changed and recompiles them. If THINK Pascal finds any er- 
rors during compilation, you'll get a bug box and a thumbs down. 


To make sure there aren't any undefined symbols or any symbols defined more than once, 
use the Check Link command. This command does a Build and then links all the files in 
your project. If there are any link errors in your project, the Check Link command tells you 
which files contain multiply defined or undefined routines. 
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Save Options 


Before THINK Pascal runs your program, it usually asks you if you want to save files that 
you've edited. It’s a good idea to save changes before you run. If you don’t save your 
changes, and your program crashes, you'll lose any unsaved edits. 


The Save Options section of the Run menu lets you specify whether THINK Pascal saves the 
changes to your edited files before running. 


Option Meaning 
Auto-Save Saves any changes automatically before running your 
program. 


If you hold the Shift key as you choose this command, 
THINK Pascal saves all the files in the project without 
changing the Save Options. 


Confirm Saves THINK Pascal asks you if you want to save changes be- 
fore running your program. 


If you hold the Shift key as you choose this command, 
THINK Pascal asks if you want to save all the files in the 
project without changing the Save Options. 


Don’t Save Don’t save any changes before running the program. 


You'll have to use the Save command in the File menu 
to save your changes. 
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Run Options 


THINK Pascal lets you set up certain run-time environment settings. Choose Run Options... 
from the Project menu. You'll see this dialog box: 


Run-time Environment Settings 


Resources 


for resources used by the project. 


Text Window saves [5000 |characters 


Text (J Echo to the printer 


Window Cjechotothefile:| sid 


Hello world. x = 811.79. 
Monaco em 


Stack size: 


zone size:|128 |kilobytes 


kilobytes 


Memory 


Resources 

The Resources section of this dialog lets you specify the resource file your program uses. 
When you click on the check box, you'll see a standard file dialog box. Choose a resource 
file, and its name appears in the box. . 


Note: The resource file must be in the same folder as the project. 


When you run your program in the THINK Pascal environment, THINK Pascal opens your 
resource file so you can access your resources. When you build your final application, 
THINK Pascal merges the resources from your resource file into the final file. 


To learn how THINK Pascal builds your project see Chapter 12. 


101 


THINK’s Lightspeed Pascal 


102 


Text Window 


The Text Window section lets you specify how much text the window saves and the font to 
display in the text window. It also lets you redirect the output to the printer or to a file. 


To send all the output from the text window to a printer, check the Echo to printer check 
box. 


To send all the output from the text window to a file, click on the Echo to file check box, and 
name the file. 


Memory 


The Memory section lets you specify how much memory your program gets while it’s run- 
ning in the THINK Pascal environment. THINK Pascal uses the stack for local variables and 
parameters. In most cases, 16K is plenty. But if a routine in your program uses a lot of local 


variables, or if your program does a lot of deep recursion, you might want to increase this 
value. 


The Zone size value tells ‘THINK Pascal how much memory to set aside for your program's 
heap. The heap contains your program’s code as well as any dynamically allocated data 
structures. Depending on the size of your program and on how much memory you allocate 
dynamically, you might want to make this value larger or smaller. 


If you’re running with MultiFinder, you may want to increase the size of the THINK Pascal 
partition when you increase the zone and stack sizes. 


Note: When you build your application, THINK Pascal uses the stack size 
value you specify. The zone size value applies only while you're running in 
the THINK Pascal environment. 


For more information on stacks and zones, see Chapter 13 and Inside Macintosh IJ, Chapter 
1, “The Memory Manager.” 


Debugging Programs 
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Introduction 


It's almost unheard of to write a program that runs perfectly the first time. THINK Pascal pro- 
vides several tools that help you track down bugs that creep into your program. This chapter 
shows you how to use them. 


THINK Pascal also provides a more advanced debugging tool — LightsBug. See Chapter 14 
after you read this chapter to learn more about LightsBug. 


The THINK Pascal editor can catch syntax errors as you type in your program. And the pro- 
ject manager can catch compiler and link errors such as undeclared variables and multiply 
defined symbols. These kinds of errors happen while you're still writing your program. 


There are other errors that turn up while you program is running. You might discover that 
your program tries to divide by zero, or that it’s trying to store a value into the seventh ele- 
ment of a six element array. THINK Pascal helps you catch run time errors by displaying a 
thumbs down icon next to the line that contains the error. 


The most insidious errors are errors of intention. Your program runs, but it doesn’t do the 
right thing. These errors occur when you forget to account for a special case or when the 
code you write doesn’t do what you think it does. 


No compiler or development system can catch these errors of intention for you, but THINK 
Pascal gives you a set of tools that makes finding errors easier and faster. THINK Pascal lets 
you watch your program as it runs. You can step through each line of your program, stop at 
any point, and examine and modify any variable. If you like, you can make temporary fixes 
to your program without recompiling, so you can see if your fixes really work. 


Topics covered in this chapter 
¢ Debugging in THINK Pascal 
¢ Following the finger 
¢ Stepping and tracing 
¢ Stop Signs 
e Restarting a stopped program 
* The Observe window 
¢ The Instant window 
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Debugging in THINK Pascal 


The basic trick of debugging is to find out what your program is really doing instead of what 
you thought it was supposed to do. The first thing to do is to run your program in a con- 
trolled way, so that you know exactly what happens when your program is running. THINK 
Pascal lets you control program execution several ways. 


° You can use the Step command to step through your program one statement at a time. 
The execution finger appears next to the line about to be executed. Your program 
stops after each statement. 


* You can use the Trace command to let THINK Pascal step through each statement auto- 
matically. This command steps through your program a statement at a time. It pauses 
briefly between statements before going on to the next statement. 


¢ You can insert one or more Stop Signs anywhere in your code. If you use the Go or 
Trace commands to run your program, it will stop whenever it encounters a Stop Sign. 
With the Go-Go command, the program only pauses at a Stop Sign. 


* You can click on the bug spray can to stop the program at any point. 
¢ You can type Command-Shift-Period to stop your program. 


Note: To use the THINK Pascal debugging tools, make sure that you've 
compiled your files with the Debug option on. 


Sometimes, just slowing program execution is enough. By watching the output of the pro- 
gram at the same time as you watch the source lines being executed, you can see what’s go- 
ing on. Often, though, you need to know the values of variables and expressions, not just 
which statement is being executed. For this kind of debugging, THINK Pascal provides the 
Instant and Observe windows. 


The Observe window lets you type in (or copy from your source file) any number of valid 
Pascal expressions (including variable names) whose value you want to know about. THINK 
Pascal updates the values in the Observe window when your program is stopped or when- 
ever your program pauses between statements. 


If your program is already stopped, you can find out the current value of a variable or ex- 
pression by typing it into the Observe window and pressing the Enter key. 


The Instant window takes things one step further. You can actually change the value of a 
variable or expression, or insert additional statements into your program, and have them 
executed on the spot — in the context of the program at the point at which it stopped. 
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Following the Finger 


Whenever your program is stopped or paused, the execution finger points to the statement 
about to be executed. 


Bullseye.p 


program Bullseye; 
const 
Scale = 8; 
var 
hPos, ¥Pos: integer ; 
Radius, i: integer; 
begin 
hPos := 100; 
vPos = 100; 
PenMode(patXor); 
for i = 100 downto 1 do 
begin 
Radius =i * Seale; 
PaintCircle(hPos, vPos, Radius) 
end 


If the file you’re stopped in doesn’t have an open edit window, the execution finger points to 
the file in the project window. 


Note: To see the execution finger, the file must be compiled with the Debug 
option on. If you compile a file with the Debug option off, you'll never see 
the execution finger in it, even if the file has an edit window. 


When the finger moves from one window to another, the new window becomes the active 
window. If you want to keep another window frontmost as you step through your program, 
you can turn off the Auto-Show Finger option in the Debug menu. For instance, if you want 
to keep the Observe window from being covered up as the edit windows become aclive, you 
would turn Auto-Show Finger off. The downside of turning this option off is that if an edit 
window is obscured, you won't be able to see the execution finger. 


Note: It’s a good idea to keep Auto-Show Finger off when you’re debug- 
ging how your application handles update events. 


If the Step Into Calls option in the Debug menu is turned off, THINK Pascal only steps or 
traces through the current block without diving into called procedures. 
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When your program is stopped, you can scroll through the editing window or switch to other 
windows to look at other parts of your program. The Show Finger command in the Search 
menu makes the window with the execution finger the active window and scrolls until the 
finger is visible. 


Stepping and Tracing 


To run a program one statement at a time, choose Step from the Run menu, THINK Pascal 
executes the first statement in the program and then stops. Choosing Step again continues 
with the next statement. THINK Pascal updates the Observe window after each Step. 


If the Step Into Calls option in the Debug menu is turned off, the finger won't step into a 
procedure or function. The procedure will be executed, and the finger will advance to the 
statement immediately following the call. 


Stepping through a program can take a long time, so you'll normally use Step when you 
want to take a very close look at a part of your program. The Trace command is the auto- 
matic version of Step. It executes your program faster than Step, but slowly enough so you 
can watch the program’s execution. THINK Pascal updates the Observe window between 
statements. 


Stop Signs 


Sometimes even tracing is too slow. You may want to run your program at full speed up to a 
specific point, and then stop it. Then you can either start stepping or tracing, possibly using 
the Observe window. 


Stop Signs let you specify the statements where you want to interrupt execution of your 
Pascal program. If you run your program with Go or Trace, the program runs until it reaches 
the Stop Sign, and then it stops. The statement at the Stop Sign is mot executed. 


Go-Go is a variation of Go where execution pauses momentarily at each Stop Sign just long 
enough to update the values in the Observe window. If there are no Stop Signs in the editing 
window, Go-Go is equivalent to Go. 


Debugging Programs ) 


To put Stop Signs in your programs, choose the Stops In option from the Debug menu. A 
Stop Sign appears in the lower left-hand corner of the active editing window, and a vertical 
bar appears along the left side. 


Bullseye.p 


program Bullseye; 
const 
Scale = 8; 
var 
hPos, vPos: integer; 
Radius, i: integer; 
begin 
hPos := 100; 
vPos = 100; 
PenMode(patXor) ; 
for i := 100 downto 1 do 
begin 
Radius := i * Seale; 
PaintCircle(hPos, vPos, Radius) 
end 
end. 
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When you move the cursor into the bar on the left side of the edit window, the pointer turns 
into a Stop Sign. Move the Stop Sign until it is directly to the left of the statement you want 
execution to stop before, and click. A Stop Sign remains in the stop bar like this: 


Bullseye.p 


program Bullseye; 
const 
Scale = 8; 
var 
hPos, vPos: integer; 
Radius, i: integer; 
begin 
hPos = 100; 
yPos := 100; 
PenMode(patXor); 
for i := 100 downto 1 do 
begin 
Radius := i * Scale; 
PaintCircle(hPos, vPos, Radius) 
end 
end. 


You can put in as many Stop Signs as you want, but only on lines that contain Pascal state- 
ments. You can’t put a Stop Sign before a comment, a declaration, a label, or an empty 
statement. 


If you turn the Stops In option off, THINK Pascal hides and ignores all your Stops Signs. If 
you turn the option on again, the Stop Signs appear again, and THINK Pascal will stop al 
them when you run your program. If you save a file with the Entire Document option, any 
Stop Signs placed in the file will be saved as part of the file. 


To remove a Stop Sign, click on it. To remove all the Stop Signs from the active window, 
choose Pull Stops from the Debug menu. 


Restarting a Stopped Program 


When you stop a program with the bug spray can or with a Stop Sign, you don’t have to start 
it all over from the beginning. If you choose one of the execution commands — Go, Go-Go, 
Step, or Trace — from the Run menu, the program continues with the next statement. 


THINK Pascal will reset your program to start again from the beginning when you edit a 
source file, change a compiler option, change a view option, or when you choose the Reset 
command from the Run menu. 
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The Observe window 


The Observe window lets you track the value of a variable or expression while your program 
is running. This window takes the place of the old debugging technique of inserting 
writeln statements into your program to print out the values of variables or expressions. 
(In fact, only values that could be printed with writeln can be observed.) 


To type an expression in the Observe window choose Observe from the Windows menu. 


Observe 


aaa 
| Enter anexpression | 


Pate Se 
Kel] ch 


You can type in any valid Pascal expressions in the cells to the right of the vertical bar in the 
middle of the window. You can Copy an expression from your program, from the Instant 
window, or from another Observe window cell and Paste it into the Observe window. The 
expressions will be evaluated and the results appear in the left cells whenever you press the 
Enter key or when your program stops or pauses. 


The Observe window uses the point at which your program stopped for the context of its 
expressions. Once the program finishes, the Observe window displays the message “No 
context.” 


It is relatively harmless to type invalid expressions or expressions with run-time errors in the 
Observe window. An abbreviated error message appears in the left hand cell. 


Some handy tips for using the Observe window: 


¢ To observe floating point numbers with precision, use the st ringof function de- 
scribed in Section 10.7.5 of Chapter 17. 

* You can use Observe to convert hexadecimal numbers to decimal. Type '$' followed 
by the hex number. The equivalent decimal value appears in the left cell.. 

¢ You can convert decimal numbers to hexadecimal by casting them to pointers. For 
example Pointer (-1) yields FFFFFFFF. 

¢ You can use the Observe window to examine variables and expressions if execution 
is stopped because of a run-time error. This powerful debugging feature can help you 
figure out the cause of the run-time error. 


THINK Pascal lets you save the contents of the Observe window. When the window is active, 
choose the Save As... command from the File menu. To open a saved Observe window, use 
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the Open... command in the File menu. The saved window replaces the contents of the cur- 
rent window. 


The Instant window 


Any time your program is stopped, you can use the Instant window to execute any THINK 
Pascal statements. Choose Instant from the Windows menu if the Instant window is not vis- 
ible, Type in and edit any Pascal statements in the window just as you would in an edit win- 
dow. Then click the Do It button to execute the statements. 


hPos := 80 


Note: If you use Command-D, you can run the code in the Instant window 
without making it the active window. 


Any Pascal statement (except a goto) is valid in the Instant window if it is legal at the point 
in the program at which execution is stopped. The statements in the Instant window are exe- 
cuted as if they were inserted into your program at the point where execution paused. You 
can even use the Instant window after a run-time error occurs. You might be able to fix the 
cause of the error and continue executing your program. 


The Instant window lets you try out new code. Type the new code in the Instant window and 
execute it. If it doesn’t work, try something else. You can do this until your code works. Then 
copy the new code from the Instant window and paste it into the program. 


Note: If you call a procedure containing Stop Signs from Instant, the Stop 
Signs are ignored. 


THINK Pascal lets you save the contents of the Instant window. When the window is active, 
choose the Save As... command from the File menu. To open a saved Instant window, use 


the Open... command in the File menu. The saved window replaces the contents of the cur- 
rent window. 
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Introduction 


This chapter goes into more detail about the components of a Pascal program. You'll learn 
how to create and use units and libraries. 


A unit is a file that is part of a larger program. Units usually handle a certain kind of action or 
deal with a particular data structure. A unit can be generic, but more often it is tailored for its 

specific role in your program. Other programming languages use the terms module or pack- 

age instead of unit. 


A library is a collection of precompiled functions and procedures. Like units, libraries usu- 
ally deal with a kind of action or handle some data structure, but libraries are more generic. 
You can use libraries in any program. 


Topic covered in this chapter 
¢ Using units 
¢ Writing units 
¢ Using libraries 
* Writing libraries 


Using Units 


A THINK Pascal program usually consists of a main program and several units. A unit is a 
collection of constants, types, variables, and procedures and functions that you use in your 
program to handle a particular set of actions or data structures. For instance, in a text editor, 
a unit might handle changing the font. In fact, this is what the ChangeFont unit of the ‘Text 
Editor example in your THINK Pascal package does. 
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To use a unit in your program or in another unit, you put the unit name in a uses clause in 
the program or unit. For example, if your program were to use a unit called Conversions, 
this is what the uses clause in your program would look like: 


program Gazelle; 


uses 
Conversions; 


. types and vars .., 


begin 
. the progran .. 
end. 


Units let you break up your program into small, manageable pieces. Usually, you’ll make 

changes only to one unit a time, and then test the changes. Because THINK Pascal recom- 
piles and relinks only the units that have changed, you’ll be able to work faster if you use 
units. 


When you view the project window by build order, all units must be listed in the order you 
use them. In other words, files that are used must precede the files that use them, with the 
main program always last. See Chapter 7 to learn how to change the build order. 


Writing a Unit 


A unit has two parts: an interface and an implementation. The interface section declares 
all the constants, types, variables, procedures, and functions that other files can see. The 
implementation section contains the code for the visible procedures and functions. The 
implementation section can also define its own types, variables, procedures, and functions, 
but these will be private to the unit. 


A unit begins with the keyword unit followed by a unit name. The name of the unit is not 
necessarily the same as the file name, but it’s less confusing if you use the same name for 
them. Just remember that when you use a unit, you give the unit name in the uses clause, not 
the file name. 


Note: You can use the View Options... dialog to have THINK Pascal 
display the name of the unit as well as the file name in the project window. 
The unit name shows only after the unit has been compiled. See Chapter 7 
for more information. 
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The interface section follows the unit name. The interface section contains the public con- 
stants, types, variables, procedures, and functions that your unit defines. For procedures and 
functions, you provide only the headers (along with the parameter lists). 


The implementation defines all the private constants, types, variables, procedures, and 
functions. The implementation section also defines the bodies of the procedures and 
functions you declared in the interface section. The procedure and function headings in the 
implementation section can contain parameter lists only if they match the parameter lists in 
the interface section. Here’s an example of a unit. 


unit Calculations; { Sample Unit - doesn’t do much } 
interface 
uses 
SANE; { The RoundPre type is defined in SANE } 
var 


DisplayWidth : integer; { This variable is exported } 


{ Public procedures and functions. The bodies are in the } 
{ implementation section } 


procedure Initialize (Precision: RoundPre) ; 
function Square (aNumber: longint) : longint; 


implementation 
const 
ConstantPrivateToCalculations = 42; 
var 
RoundPrecision: RoundPre; 


procedure Initialize (Precision: RoundPre) ; 


begin 
RoundPrecision := Precision; 
SetRound (RoundPrecision) ; 
end; 
function Square (aNumber: longint) : longint; 
begin 
Square := aNumber * aNumber; 
end; 


procedure PrivateToCalculations(x: integer) ; 
begin 
end; 

end. 
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The program that uses this unit would be in another file and would look something like this: 


program Gazelle; 


uses 

SANE, Calculations; The program uses SANE because } 
the TowardZero constant is } 
defined there, and because } 
Calculations uses it in its } 


interface part } 


var 
aNum : longint 


{ more declarations } 


begin 
Initialize (TowardZero); { Public proc in Calculations unit } 
aNum := Square (1961); 

end, 


In this example, the main program would not be able to call the procedure 
PrivateToCalculations or use the constant ConstantPrivateToCalculations 
because both are defined only in the implementation section of the unit and not in the 
interface, 


The uses clause specifies the dependencies between the files that make up a program. 
THINK Pascal uses this dependency information to determine which files are affected by an 
edit. Whenever you change the interface section of a unit, THINK Pascal recompiles all the 
files that use it. 


Using Libraries 


A library is like a unit in that it contains procedures and functions to perform an action or to 
manipulate a particular data structure. But unlike units, a library is made up of of compiled 
code and can consist of more than one Pascal file. 


To use a library, you simply add it to your project with the Add File... command in the 
Project menu. Most of the time, a library has an associated interface file. The interface file is 
a unit that contains the type declarations and calling sequences for the procedures and 
functions defined in the library. To add the interface file, use the Add File... command. 


Your THINK Pascal package comes with several libraries. The next chapter tells you what's in 
each library. 
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Writing Libraries 


Writing a library is like writing a unit. In fact, a library is made up of one or more units, The 

difference between adding a library into your project and adding the units that comprise the 
library into your project is that a library consists of compiled code whereas you would have 
to compile each unit. In most cases, you won’t even have the source code for libraries. 


To create a library, make a new project and add all the units that comprise it. Then use the 
Remove command in the Project menu to remove Interface.1lib and Runtime. lib. 
If you leave these two libraries in your library, any project that uses them and your library 
will have multiply defined symbols. Then use the Build Library... command in the Project 
menu to create your library. A standard dialog box will appear asking you to name the 
library. By convention, libraries end in . Lib. 


Your library must conform to these three constraints: 


* There must be only one code segment in the project. 
¢ There must be at least one file in the project. 
¢ There must be no main program, only units. 


Writing the interface file 

Because the library consists of compiled code, there’s no way for your program to know how 
to call the procedures and functions in it. You need to create the interface file to let the 
program that uses your library know what the routines are called and how to call them. The 
interface file also defines the public types you use in the library. 


Note: Pascal doesn’t let you reference external variables in libraries from 
your program. You can write routines in your libraries that access and set 
global variables, though. 
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For instance, suppose you created a library, Names . 1ib, that contains several procedures 
and functions that deal with names in a list. Your interface file might be called 
NamesIntf£.p and look like this: 
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unit NamesIntf; 
interface 


type 
{ This is a type your program can use. The library may } 
{ define private types that your program can’t “see” } 
Str32 = string[32]; 
NameRec = record 
FirstName: Str32; 
LastName: Stxr32; 
end; 


function AddName(first: Str32, last: Str32): integer; 
function FindName(ix: integer; var theName: NameRec) :Boolean; 
procedure DelName(ix: integer) ; 


implementation 


{ These declarations are optional because THINK Pascal } 
{ defaults them to external. } 

function AddName (first: Str32, last: Str32): integer; 
external; 


function FindName(ix: integer; var theName: NameRec) :Boolean; 
external; 


procedure DelName(ix: integer); 
external; 


end. 


To use the library, you would add NamesInt f.p and Names. 1ib to your project. The unit 
that calls procedures and functions from Names .1ib would have the clause uses 
NamesIntf in it. 


The interface file looks just like a unit. The interface section shows what procedures and 
functions are public and how they should be called. The implementation section is a little bit 
different. Instead of defining the bodies of the procedures and functions, it contains the rou- 
tine headers and then the directive external. 


Note: If there is no definition of a procedure or function declared in the 
implementation part, THINK Pascal assumes that the procedure or function 
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is external. It's a good idea to declare these routines external explicitly to 
make your intentions clear to others who use your libraries. 


The external directive 


The external directive tells the compiler that the body of the procedure or function is not 
there, but that it should try to find it when the linker tries to link the program. 


Usually, you use the external directive in the implementation section of interface files for 
libraries or to access procedures and functions that were originally written in assembly lan- 
guage. But you can use it to describe the calling sequence for a procedure or function that 
isn’t in a used unit. 


Note: To learn more about using assembly language routines in THINK 
Pascal, see Chapter 13. 


For example, if you added the library Names.lib from the example above into your project, 
and you didn't want to add the interface file, you could just write: 


function AddName (first : Str32, last : Str32) : integer; 
external; 


in the file that uses AddName to define the calling sequence for the AddName function. 


Generally speaking, you should limit use of the external directive to an interface file. 
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Using Predefined Routines 
11 


Introduction 


THINK Pascal predefines all of the standard Pascal procedures and functions as well as the 
most common Macintosh Toolbox routines. Your THINK Pascal package also includes sev- 
eral libraries for those routines that aren’t built into the compiler. This chapter shows you 
what you need to do to access the standard Pascal procedures like write, writeln, abs, 
etc. and how to access the Macintosh Toolbox routines described in Inside Macintosh. 


Topics covered in this chapter 


¢ Calling standard Pascal routines 
¢ Calling Macintosh Toolbox routines 


Calling Standard Pascal Routines 


THINK Pascal provides a large number of predefined procedures and functions. When you 
create a new project, two libraries are automatically added to it. The library Runtime .1ib 
contains all of the standard Pascal routines like writeln, readln, and abs, as well as rou- 
tines that the compiler uses for sets, 32-bit multiplies, and so on. Runtime. 1ib also con- 
tains some procedures and functions for compatibility with Symantec’s (formerly Apple’s) 
Macintosh Pascal. For a complete description of the THINK Pascal predefines, see Sections 9 
and 10 of the Language Reference (Chapter 17). 


Depending on the type of project you're building you may use different versions of 
Runtime. 1ib. The default Runtime. 1ib that’s included in every THINK Pascal project 
you create is rather large because it’s supporting all of the Pascal input/output and the code 
that manages the Text window. 


If you’re writing a Macintosh application, and you're not using any of the Pascal input/output 
routines, you can use a smaller version of Runtime.1ib called wRuntime.1ib. This 
version of the library does not contain any Pascal input/output routines, so you can't use the 
Text or Drawing windows. 


If you’re writing a desk accessory, device driver, or code resource, you cannot use 
Runtime. 1ib or WRuntime.1ib because both libraries reference their globals through 
register AS. For these types of projects, you'll need to use DRVRRunt ime. 1ib which is 
similar to URuntime. lib, but uses register A4 to access its globals. The next chapter shows 
you how to build these kinds of projects. 
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If you need to customize these libraries for your own use, you can open the projects 
Runtime .7, WRuntime.z, and DRVRRuntime.1 and remove the parts of the libraries you 
don’t want. Since the sources for these libraries are not in your THINK Pascal package, be 
sure you don’t work with your original files. When you've removed what you don’t need, use 
the Build Library... command in the Project menu to create a new library. 


Calling Macintosh Toolbox Routines 


THINK Pascal lets you use all the Macintosh Toolbox routines described in Inside Macintosh 
/-Vincluding those marked [Not in ROM] . To use the Toolbox routines, call them exactly 
as they appear in Inside Macintosh. 


Most of the Toolbox routines in Inside Macintosh I-V are predefined in THINK Pascal, so you 
don’t have to do anything special to use them. The constants, types, and routines are built 
into THINK Pascal. The library Interface.1ib contains the “glue” code for Toolbox 
routines that aren’t stack-based. 


THINK Pascal generates in-line calls for all of the stack-based traps. For the register-based 
traps, routines marked [Not In ROM], and for routines that work off dispatched traps, 
THINK Pascal uses the “glue” code in Interface. 1ib so you can call them as Pascal pro- 
cedures and functions. 


For the less common routines, you need to add specific libraries and interface files to your 
project. 


Note: This section assumes you already know what interface files and li- 
braries are. If you need to learn about them, see Chapter 10. 
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Differences in THINK Pascal 

Some of the types defined in Inside Macintosh are implemented a little differently in THINK 
Pascal. Generally, any type defined in Inside Macintosh that uses bit-packing is defined as a 
scalar type in THINK Pascal. These are the major differences. 


Type from Inside Macintosh Is defined like this in THINK Pascal 
KeyMap = KeyMap = array [0..3] of longint 
packed array [0..127] of boolean 

{ 16 bytes } 


BitMapType = BitMapType = SignedByte 
packed array [0..7] of boolean 
{ 1 byte } 


StageList = StageList = Integer; 
packed array [1..4] of 
record 
boldItem: 0..1; 
boxDrawn: boolean; 
sound: 0..3 
end; { 4 bits/record } 


To access the elements of bit-packed arrays, use the BTST and BSET routines described in 
sections 10.7.13 and 10.7.14 of Chapter 17. The zeroth element of a bit-packed array is bit 
zero of the byte. The elements of the KeyMap type are arranged like this: 


byte 0 byte 1 byte 15 


Calling QuickDraw routines 


The standard QuickDraw routines described in Inside Macintosh Iare predefined in THINK 
Pascal. You don’t need to do anything special to use them. To use the more advanced Color 
QuickDraw routines, you need to use the QuickDraw.p interface file. 


121 


THINK’s Lightspeed Pascal 


122 


THINK Pascal lets you use an alternate parameter list for the QuickDraw graphics operations 
on Rects, RoundRects, Ovals and Arcs. Instead of using a temporary Rect variable, you can 
supply the rectangle coordinates in the parameter list. So you can replace this: 


var 
rirect; 

begin 
SetRect (r, left, top, right, bottom); 
FillRect (r, dkGray); 

end; 


with this: 


FillRect (top, left, bottom, right, dkGray); 


Note: The order of the arguments to Set Rect is different from the order of 
the arguments to the QuickDraw routines. The alternate parameter list uses 
the same order as the Rect record declaration. 


You can use the alternate parameter list with these 20 procedures: 


EraseRect EraseRoundRect EraseOval EraseArc 
FillRect FillRoundRect Filloval FillArc 
FrameRect FrameRoundRect FrameOval FrameArc 
InvertRect InvertRoundRect InvertOval iInvertArc 
PaintRect PaintRoundRect PaintOval PaintArc 


The function GetMouse, which usually takes a point as a parameter, can also take two pa- 
rameters; 


procedure GetMouse(var h : integer; var v : integer); 


Calling AppleTalk routines 


If your application uses AppleTalk routines, you should be aware that there are now two 
versions of AppleTalk. Apple calls the old version (described in Inside Macintosh I) the 
alternate set. The new version, described in Inside Macintosh V, is called the preferred set. 
You'll use a different library depending on which version of AppleTalk your application uses. 


To use... Use this interface file and library 
preferred AppleTalk AppleTalk.p / nAppleTalk.lib 
alternate AppleTalk AppleTalk.p / ABPackage.lib 
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Calling Printing Manager routines 

The Printing Manager is available through ROM traps in the Macintosh SE and Macintosh II 
and through RAM patch code in System Tools 5.0 and later. For earlier Macintoshes that can't 
run System Tools 5.0 or later, the Printing Manager is available as a library. 


Note: System Tools 5.0 consists of System 4.2 and Finder 6.0. To find out 
what System version your program is running under, use the 
SysEnvirons procedure (see Inside Macintosh V, Chapter 1, 
“Compatibility Guidelines.”) 


The standard printing libraries include both calls to the traps and the Printing Manager code. 
If you know that your application is going to run only on machines running System Tools 5.0 
or later, you can use a traps-only version of the Printing Manager library. If you use the spe- 
cial version, your application will be smaller, but it won’t run on machines that are using 
Systems earlier than System Tools 5.0. 


If your application requires... Use this interface file and library 
any System/Finder version MacPrint.p / PrintCalls.lib 
System Tools 5.0 or later PrintTraps.p/no library 


Calling SANE routines 
THINK Pascal lets you choose whether to generate code for the MC68881 math coprocessor. 


If you’re using the MC68881 option, and you’re using SANE, you’ll need to use a special ver- 
sion of the SANE library. 


If you're... Use this interface file and library 
using the MC68881 option SANE.p / SANE881.1lib. 
not using the MC68881 option SANE.p / SANE.1lib 


Calling Serial Driver routines 


If your application uses the RAM serial driver described in Inside Macintosh I, Chapter 9, 
“The Serial Drivers,” and you want to make sure that it will run on a Macintosh equipped 
with the 64K ROM, you'll need to add a SERD resource to your application’s resource file. 
The SERD resource was incorporated into the 128K and later ROMs, so you don’t need the 
resource if your application runs only on Macintosh 512Ke and later machines. The SERD re- 
source is in the file called SERD in the Libraries folder. 


Note: To learn how THINK Pascal handles resources for your application, 
see Chapter 8 and 12. 
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Calling other Toolbox routines 


To use other routines, particularly those specific to the Macintosh II, you'll need to add these 
interface files. (The names of the units are the same as the names of the files without the . p 
suffix.) 


To use... Use these interface files 

3D Graphics Graf3D.p and Graf3D.lib 
ADB Manager OSIntf.p 

Color Control Manager ToolIntf£.p 

Color Menu Manager ToolIntf.p 

Color Picker Package PickerIntf.p 

Color Window Manager ToolIntf.p 

Fixed Math FixMath.p and FixMath.1lib 
Palette Manager Palette.p 

Script Manager Script.p 

SCSI Manager SCSIIntf.p 

Slot Manager OSIntf£.p, ROMDefs.p, VideoIntf.p 
Sound Manager Sound.p 

Text Edit with styles Toolintf.p 
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Introduction 


You can write applications, desk accessories, device drivers, and code resources in THINK 
Pascal. This chapter tells you how to build the different kinds of projects. 


What you should know 

You should know how to use THINK Pascal. You should know how to create a project and 
how to add files and libraries to a project. You should know how to run your program in the 
THINK Pascal environment. If you don’t know how to do these things, go back to Chapter 7 
and to Chapter 8. 


If you want to write Macintosh applications, you should know about the resources that make 
up an application: menus, window templates, dialog manager, control templates, etc. You 
should know how to build these resources with a resource editor like ResEdit or with a 
resource compiler like RMaker. To learn about resources read Inside Macintosh I, Chapter 5, 
“The Resource Manager.” Other chapters in Inside Macintosh discuss different kinds of 
resources. 


If you want to write desk accessories or device drivers, you should be familiar with the me- 
chanics of DRVR resources. These are a bit more complicated than other resources. See /nside 
Macintosh I, Chapter 14, “The Desk Manager” and Inside Macintosh II, Chapter 6, “The 
Device Manager” to learn about DRVR resources. 


If you want to build other kinds of resources (INITs, WDEF's, XCMDs, cdevs, etc.) see 
“Building Code Resources” later in this chapter. 


If you don’t know how to call the Macintosh Toolbox routines from THINK Pascal, read 
Chapter 11. 


Topics covered in this chapter 
* Setting the project type 
© Using resource files 
¢ Building applications 
¢ Building desk accessories and device drivers 
¢ Building code resources 
¢ Putting it together 
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Setting the Project Type 


Before you begin working on a project, you set the project type. When you set the type, 
you let THINK Pascal know how to build your program into a finished file. To set the project 
type, choose the Set Project Type... command from the Project menu. You'll see this dia- 


log box: 


File Information 


Type: Creator: 


Reseurce Jaformation 


& Bundle Bit 


nustom Header 


Belay 


aiti-Seqment 


To set the type of project click on one of the four icons along the left of the dialog. 
Depending on which icon you choose, the gray parts of the dialog may become active. 


The rest 


projects, 


Note: Changing the project type doesn’t mean that your program will be- 
have differently. For instance, if you change the project type from 
Application to Desk Accessory, your application won’t turn into a desk ac- 
cessory automatically. There are different rules for writing the different kinds 
of projects, 


of this chapter goes into detail about the different kinds of projects. For all types of 
though, you'll need to fill in the file information section. This section lets the Finder 


know what kind of file you're creating and how to display it on the desktop. 


The file type lets the Finder know what kind of file it is. For applications, the type is APPL. 
Other kinds of files have other types. Text files, for instance, have the type TEXT. The creator 
field identifies the application that created the file. If the file type is APPL, the creator is the 
unique four character signature of the application. 
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If you check the Bundle bit check box, THINK Pascal will set the bundle bit in the file’s 
Finder information record. The Bundle bit lets the Finder know that your application has a 
BNDL resource and that it has its own icon. 


To learn more about the file type, the file creator, and the bundle bit, see Inside Macintosh 
III, Chapter 1, “The Finder Interface.” 


Using Resource Files 


When you launch an application from the Finder, it looks in the resource fork of the applica- 
tion for its resources. When you run your program in the THINK Pascal environment, it’s not 
quite an application yet, so your program needs to know where it can find its resources. 


The Resources section of the Run Options... command in the Project menu lets you specify 
where your program should expect its resources. When you choose the Run Options... 
command, you'll see this dialog box: 


Run-time Environment Settings 


(Use resource file: 
for resources used by the project. 


Resources 


Text Window saves [5000 |characters 


(Echo to the printer 


Hello world. x = 811.79. 
Monaco | 9 | 


Stack size: 


Zone size:[128 |kilobytes 


When you click in the Use resource file: check box, you'll see a standard file dialog. Choose 
the file that contains the resources for your program. The name of the file you select appears 
in the box. 


Note: THE RESOURCE FILE MUST BE IN THE SAME FOLDER AS THE 
PROJECT. 
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When you run your program in the THINK Pascal environment, THINK Pascal will open your 
resource file so you can access your resources. 


When you’re ready to build your project into a standalone application, THINK Pascal copies 
the resources in your project’s resource file into the final application file. 


You can use RMaker or ResEdit to create resource files. Both of these are in your THINK 
Pascal package on the disk THINK Pascal 2. To learn how to use RMaker, see Appendix 
D. ResEdit is more intuitive. Complete documentation for ResEdit is available from APDA. See 
Chapter 1 for APDA’s address. 


By convention, files that contain resources to be used as part of a project end in . rsrc. 


Building Applications 


‘THINK Pascal is set up to build applications by default. When you set the project type, all you 
need to do is give your application a creator. If the application you’re writing is a one-shot — 
it doesn’t need its own icons, and it doesn’t create its own files — you can just take the de- 
faults and not bother with the Set Project Type... dialog. 


Toolbox initialization 


When your program starts up, THINK Pascal inserts calls to the following Toolbox initializa- 
tion routines for you: 


InitGraf (@thePort) ; 
InitFonts; 
InitWindow; 
InitMenus; 
TEInit; 
InitDialogs (nil) ; 
SetApplLimit (value of A7 - value of Run Options stack size); 
MaxApp1lZone; 
for i := 1 to 10 do 
MoreMasters; 


If you call these routines while your program is running in the THINK Pascal environment, 
nothing happens. If you leave them in your final application, your application will crash 
when it starts. 


If you’re porting code from other development systems, and that code includes these initial- 
ization routines, you can use the {$I-} compiler directive immediately after the program 
statement to disable the automatic initialization. To learn more about compiler directives, see 
Chapter 15. 
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Text and Drawing windows 


When your program is running in the THINK Pascal environment, you can use the Text and 
Drawing commands in the Windows menu to display the Text and Drawing windows. If 
your program uses these windows, you'll need to use the following procedures to work with 
the Text and Drawing windows ina standalone application: 


ShowText SetTextRect 
ShowDrawing SetDrawingRect 
HideAll 


See section 10 of Chapter 17 to learn more about these procedures. 


Running the project 

When you use one of the execution commands — Go, Go-Go, Step, or Trace — in the 
Project menu, THINK Pascal runs your program in an environment that resembles the stan- 
dard Macintosh software environment. 


To learn more about running your project in the THINK Pascal environment, see Chapter 8. 


Building the application 

When you're finished debugging your application, use the Build Application... command 
in the Project menu to create your application file. Read the section “Putting it Together” at 
the end of this chapter to learn how THINK Pascal creates your final application. 


Building Desk Accessories and Device Drivers 


Desk accessories and device drivers are structurally identical; they're both drivers. According 
to Inside Macintosh, drivers don’t behave like applications and have a different internal 
structure. In this section, the word driver means either a desk accessory or a device driver. 


This section won't teach you how to write a desk accessory or a device driver from scratch. 
To learn how to write these, read Inside Macintosh I, Chapter 14, “The Desk Manager,” Inside 
Macintosh I, Chapter 6, “The Device Manager,” and Inside Macintosh V, Chapter 23, “Ihe 
Device Manager.” 


Setting the project type 
Set the project type before you start working on a driver. If you set the project type after 
you've started compiling code, you'll have to recompile your source files. 


Choose Set Project Type... from the Project menu. When the project type dialog appears, 
click on either the Desk Accessory icon or the Device Driver icon. 


The Desk Accessory dialog presets the file type and creator so the resulting file will be a 
Font/DA Mover file. The ID is set to 12. The Font/DA Mover renumbers it when you install it 
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in your System. You shouldn't need to change the ID number. All that’s left to do is to name 
the desk accessory and write the code. By convention, desk accessory names begin with a 


NUL (chr (0) ). THINK Pascal provides it for you automatically. 


File Information 


eS | ayoe: (FT [pFit_| Creator: CBundle i) 


Application 


r— Resource Information —————————————__, 
ee | Name: 
IDesk Accessoru 
Type: |DRUR ID: (te — 


OD custom feader 


es Attributes: = 


r— Driver Information 


Code Resource 


The Device Driver dialog is a little bit different. Device driver names begin with a period. If 
you don’t provide one in the Name field, THINK Pascal automatically provides one for you. 


r— File Information 


eS creator: Obundte sit 


Application 


r— Resource Information 


Driver Information 


(Multi-Segment 
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Note that the Flags field of the Driver Information section is different for desk accessories and 
device drivers. Later on you'll see what these two fields mean. 


Before you start working on your driver, you need to do one more thing. You need to re- 
move the default Runt ime. 1ib library and replace it with the special DRVRRuntime.1ib 
library. This library is like Runtime .1ib except that it uses register A4 to access globals, 
and it does not contain the Pascal I/O routines. (This means that you can’t use writeln ina 
desk accessory, for instance.) 


Note: To change the library, hold down the Option key as you double-click 
on the library name. THINK Pascal displays a standard file dialog that lets 
you choose the replacement file. 


Both device drivers and desk accessories can have more than one segment, just like appli- 
cations. Just click on the Multi-Segment check box. You can learn more about multi-segment 
drivers below, but read how a driver works first. 


Note: If your driver uses Object Pascal, you must check the Multi-Segment 
option even if your driver contains only one segment. 


How drivers work 

The Device Manager expects drivers to have five entry points and to be written in assembly 
language. When the Device Manager calls a driver written in THINK Pascal, a short assembly- 
language stub translates the Device Manager's request into a call to a Pascal function called 
main. THINK Pascal automatically places the driver glue at the beginning of your driver. 


The THINK Pascal driver glue also does two things designed to make writing a driver easier. 
First, it sets up a data area so that your driver can have its own global variables. Second, it 
figures out the proper way to return control to the Device Manager automatically. You'll learn 
more about these services later in this section. 
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How to write a driver in THINK Pascal 


To write a driver in THINK Pascal, you have to follow two rules. The first rule is that a driver 
must consist only of units. It may not have a file with a main program. The second rule is that 
a driver must have a function called main defined in one of its units, and that function must 
also appear in its interface section. This is the skeleton for a THINK Pascal driver: 


unit MyDeskAccessory; 
interface 


function main(devCtlEnt: DCtlPtr; paramBlock: ParmBlkPtr; 
sel integer): integer; 


implementation 


function main; 


begin 
case sel of 
0: { Open } 
1: { Prime } 
2: { Control } 
3: {, Status. } 
4: { Close } 
end 

end; 


end. 


The function main takes three arguments that let you know how your driver is being called. 


The first argument, devCt1Ent, is a pointer to the driver’s device control entry. This is the 
value that is passed in register Al to the assembly language entry point of the driver. 


The second argument, paramBlock, is a pointer to an I/O parameter block. This is the 
value that is passed in register AO to the assembly language entry point of the driver. 


The last argument, se1, is a selector that specifies which entry point actually received the 
call. Use the value of sel to dispatch control to the appropriate routine. 


Getting the event record pointer from the parameter block 

According to Inside Macintosh I, Chapter 14, “The Desk Manager,” the csCode field of the 
paramBlock passed to your driver specifies what kind of action your driver should take. 
When paramBlock*.csCode = accEvent, the csParam field of paramBlock con- 
lains a pointer to an Event Record. 
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The csParam field is defined as an array of integers, so you'd have to cast the first two inte- 
gers of the array into the pointer to the event record. It’s much easier to use the ioMisc 
field, which is defined in another variant of ParamBlockRec, because it points to the right 
place in memory, and it’s already a pointer. 


var 
EventP : *EventRecord; 


EventP := Pointer (paramBlock*.ioMisc) ; 


Global data in drivers 

You can declare global and static variables in drivers. The THINK Pascal driver glue allocates 
the space for the globals in the heap before it calls main to implement the Open entry, ‘he 
glue releases the memory when the driver returns from a Close call. (There is a way lo keep 
the global data area allocated after a Close; see “Returning from a driver” below.) 


Note: All of the globals in your driver are guaranteed to be set to zero on the 
first Open call. 


Macintosh applications use register A5 to access their globals. Since drivers co-exist with run- 
ning applications, they can’t use register AS to access their globals. Instead, drivers use regis- 
ter A4. 


The THINK Pascal driver glue stores a handle to the dynamically allocated data area in the 
act 1Storage field of the driver's device control entry. This handle is dereferenced into ad- 
dress register A4 and locked before each call to main. Your Open routine must check 
whether the data area was allocated successfully. If it was not, the dct1Storage field will 
be 0, and your driver should display some error message (without using any globals!) and 
close itself. Your code might look like this: 


if devCtlEnt*.dCtlStorage = nil then 
begin 

SysBeep (5); 

EXIT (main); 
end; 


The data area remains locked between calls to your driver. If you like, you can unlock it 
yourself before returning. If you unlock the data area, though, make sure that you don't rely 
on the address of any data item staying the same between calls. Also, make sure that the data 
area docsn’t contain any objects, such as windows, that the Toolbox assumes will not move. 


Using driver globals in callback and trap intercept routines 


The THINK Pascal driver glue sets up register A4 for you whenever your driver is called from 
main. If your driver defines callback routines, trap intercept routines, or other functions that 
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might be called when the value of A4 is in doubt, you have to save A4 where your routines 
can find it. 


The special library for drivers, DRVRRuntime.1ib, contains the procedures RememberA4, 
SetUpA4 and RestoreA4 that take care of saving, setting, and restoring A4 for you. 


Your main routine must call RememberA4 before any calls to SetUpA4. All calls to 
SetUpA4 and RememberA4 must be from the same segment that contains main. This 
means that the file that contains main, DRVRRuntime.1ib, and any files that contain calls 
lo SetUpA4 and RestoreA4 must be in the same segment. 


Suppose your driver calls ModalDialog with a £ilterProc. Since you're not sure if the 
value of A4 will be correct when ModalDialog calls your £ilterProc, you need to set 
A4 to the proper value. Your £ilterProc would look like this: 


function MyFilterProc(dp : DialogPtr; var event: EventRecord; 


var item : integer) : Boolean; 
var 
result : Boolean; 
begin 
SetUpA4; { main must call RememberA4 first! } 
MyFilterProc := result; 
RestoreA4; 
end; 


Your main routine would look like this: 


function main; 
begin 
RememberA4; { Stash A4 where SetUpA4 knows } 
{ where to find it } 


case sel of 


0: { Open } 

1: { Prime } 
2: {Control |}. 
3: { Status } 
4: { Close } 
end 


end; 
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Use the same technique for trap intercept routines that need access to a driver’s globals. Of 
course, if your callback or trap intercept routine doesn’t use driver globals, you don’t need to 
set up and restore A4. 


Using libraries in drivers 

You can use libraries in drivers as long as the libraries don’t reference global variables ac- 
cessed through register A5. The special version of the run-time library for drivers, 
DRVRRuntime.1ib, was built so it references its globals from A4. 


The QuickDraw globals aren’t in DRVRRuntime.1ib, You can access the real QuickDraw 
globals in a driver from assembly language by observing that 0 (A5) holds the address of the 
last of the QuickDraw globals, thePort. The remaining QuickDraw globals are at descend- 
ing addresses from thePort; refer to Inside Macintosh I, Chapter 6, “QuickDraw” for more 
information. The value of AS is stored in the low-memory global CurrentAS. 


Note: The only reason most people need to use the QuickDraw globals 
from a driver is to get the bounds of screenBits. A common trick to get 
this information from a driver is to create a new GrafPort. The default 
portBits is the same as screenBits. Don't forget to get rid of the port 
once you have what you want. 


You can use most of the libraries supplied with THINK Pascal (PrintCalls, nAppleTalk, 
FixMath, Graf3D, etc) in your drivers. You can’t use Runtime.1ib or Runtime. lib. 


Setting the fields of a driver’s header 

A driver begins with a header that contains several flags and other data items (some of which 
apply only to desk accessories), When the driver is opened, the Device Manager copies these 
fields to the device control entry before the Open entry point is called. After that, the device 
header is not used. The fields in the driver are used only to initialize the fields in the device 
control entry. 
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THINK Pascal lets you set the drvrFlags and the drvrEMask fields in the Set Project 
Type... dialog.Use the two pop-up menus to set the flags you want. 


File Information 


Type: Creator: |DMOU C1 Bundle Bit 


Resource Information 


Name: 


Application 


Ol eustom fieader 


orien Driver Information 


0400 | Delay: [0 | 
Code Resource “mousepown CMulti-Segment 


vkeyDown 
vautoKey 
/updateEvt 
vactivateEut 


These two fields are copied to the dCt 1FLags and dCt 1EMask fields of the device control 
entry. 


These are the default settings for desk accessories, The symbols dReadEnable, 
dWritEnable, etc refer to bits of the high byte of the drvrFlags. DReadEnable is bit 0, 
dNeedLock is bit 6. When you set the flag yourself, leave the other bits clear. 


Field Value 

dctlFlags $0400 
dReadEnable 
dWritEnable 
dctlEnable 
dStatEnable 
dNeedGoodbye 
dNeedTime 
dNeedLock 0 

dct1lDelay N/A because dNeedTime = 0 

dactlEMask 0x016A (mouseDown, keyDown, autoKey, 
update, activate) 

dct1Menu 0 


ooorao 
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These are the default settings for device drivers: 


Field Value 
dctlFlags $4F00 
dReadEnable 1 
dWritEnable 1 
dctlEnable 1 
dStatEnable 1 
dNeedGoodbye 0 
dNeedTime 0 
dNeedLock 1 
dctlDelay N/A because dNeedTime = 0 
act lEMask N/A (desk accessories only) 
dct1Menu N/A (desk accessories only) 


THINK Pascal copies the fields from the driver’s header to the device control entry on every 
Open call. If you want to change the settings of the driver headers on the fly, you'll need to 
set them on every Open call. 


Opening an open driver 

The Open entry point of a driver (main’s third argument = 0) may be called even if the driver 
is already open. This happens, for example, when the user selects the name of a desk acces- 
sory that’s already on the screen, The driver should check to see if it is already open to avoid 
repeating its initialization sequence. 


Since THINK Pascal guarantees that all your driver globals will be set to zero, you can use a 
global flag to determine whether your driver's been opened before. Your Open routine might 
look like this: 


procedure doOpen; 


begin 
{ AlreadyOpen is boolean a global. } 
if AlreadyOpen then 
EXIT (doOpen) ; 


AlreadyOpen := TRUE; 


{ Initialization code } 
end; 


How to return from a driver 


If your Open routine was successful, return 0. If the Open routine fails, return a negative re- 
sult and the driver will not be opened. 
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Return 0 from Close if it was successful. If your Close routine returns closeErr (-24) the 
driver won't be closed. If you return a 1, the THINK Pascal driver glue will preserve the 
dCt1Storage field of the device control entry. This way you can keep your driver globals 
around until your driver is reopened. (The driver glue will make it seem as though your 
Close routine returned 0, meaning the Close was successful.) 


Note; Returning negative values from Open and Close to prevent opening 
or closing works only on 128K and later ROMs. 


Return 1 from asynchronous calls to Prime, Control, and Status routines if the request 
could not be completed right away. This result code will be stored in the ioResult field of 
the I/O parameter block, but 0 (no error) will be returned to the Device Manager. 


The jlODone problem 


THINK Pascal always returns from a driver correctly. In other development systems, it’s not 
so easy. Read this section if you want to learn about this problem. Since you don’t have to 
worry about it, you might want to skip this section. 


One of the trickiest aspects of returning from a driver is deciding whether to return directly to 
the Device Manager (via an RTS instruction) or whether to jump to j1ODone. This is a com- 
plex issue, and many existing desk accessories do it wrong (though, fortuitously, they man- 
age to work anyway). 


Associated with each driver is an I/O queue, which is a list of I/O parameter blocks waiting 
for service from the driver, Calls made to a driver fall into one of two categories: queued, 
meaning that the I/O parameter block passed as an argument to the call is in the driver's 
queue; and immediate, meaning that it is not. In the immediate case, the queue may even be 
(and in fact usually is) empty. 


All Open and Close calls are immediate, All Cont rol calls made to desk accessories are 
immediate, except for the “goodbye kiss” (csCode=-1) issued to desk accessories that have 
requested to be notified when the current application exits out from under them. Other calls 
may be queued or immediate. 


The rules for returning from a driver are: The driver should return directly to the Device 
Manager from all immediate calls. It should also return directly to the Device Manager from 
queued calls requesting asynchronous I/O that could not be completed right away. Finally, it 
should jump to jI1ODone from queued calls if the driver completed the request (or if there 
was an error). 


It is incorrect to violate these rules; in particular, it is incorrect to jump to }IODone to return 
from an immediate call. j 1ODone will attempt to examine the driver’s I/O queue, and since 
the queue is usually empty it will end up examining low-memory locations beginning at 
$0000. Apparently, these locations somehow look enough like an I/O parameter block to 
satisfy the Device Manager, but this is clearly an unsafe situation. 
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Just to make things difficult, when returning from Prime, Control, and Status calls, it is 
jIODone that unlocks the driver’s code and its device control entry so they won’t form is- 
lands in the heap between calls to the driver (unless, of course, the driver has requested that 
they remain locked). So the author of a desk accessory, for instance, has to make a difficult 
decision — to return directly to the Device Manager, leaving the driver's code and its device 
control entry locked and potentially interfering with the host application; or to violate the 
rules and jump to j1ODone. Most desk accessories seem to take the latter route. 


THINK Pascal avoids this dilemma. When a driver written in THINK Pascal returns from 
main, the decision whether to call jI1ODone is made automatically (and correctly). For 
Prime, Control, and Status calls, if the decision is made to return directly to the Device 
Manager, and the driver has not requested that its code and device control entry remain 
locked, they are unlocked. 


Multi-Segment drivers 

If the Multi-Segment option is on, drivers can contain multiple segments. As with appli- 
cations, segments are loaded automatically as they are called. In addition, all loaded seg- 
ments are unloaded automatically upon return to the Device Manager after each call, unless 
the dNeedLock bit is set in the driver’s device control entry. 


You can unload driver segments manually with this function: 


procedure UnloadA4Seg(theProcPtr: ProcPtr); 
This function works just like UnloadSeg does in applications. 
Note: Do not use UnloadSeg instead of UnloadA4Seg by mistake! 


Read “Arranging Files in the Project” in Chapter 7 to learn how to break up your project into 
segments. 


Note: If your driver uses Object Pascal, you must check the Multi-Segment 
option even if your driver contains only one segment. 


Running desk accessories 

You can’t run a desk accessory with one of the execution commands in the Run menu be- 
cause desk accessories aren’t real applications. (They don’t even have a main program!) To 
run a desk accessory, use the special DA Shell program that’s included in your THINK 
Pascal package. 


The DA Shel] is a small program that simulates an environment for your desk accessory. It 
takes advantage of the fact that a desk accessory is a unit and that it’s called through the 
functionmain. The DA Shel] creates a fake device control entry and a fake I/O parameter 
block for your main function. 
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To use the DA Shell 
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* Make a backup copy of the DA Shell file 

* Create a new project with the default libraries 

¢ Add your desk accessory units to the project 

¢ Add the DA Shell file to the project 

* Inthe DA Shell file, put your desk accessory’s unit name in the uses clause 


To run your desk accessory, choose one of the execution commands — Go, Go-Go, Step, or 
Trace — from the Project menu, then choose Sample DA from the Apple menu. When you 
use the DA She11, you can use any of THINK Pascal's debugging tools to debug your desk 
accessory. 


Desk accessories that work in the DA Shell should work properly as real desk accessories. 
But since the DA She11 is a simulated environment, you should be aware of several things: 


When your desk accessory is running in the DA She11, events in your windows look 
like incontent. When you run your desk accessory as a real desk accessory, these 
events will be inSysWindow. At least while you're debugging, your desk accessory 
should treat inContent hits as inSysWindow hits. 


If your desk accessory uses owned resources, calculate the unit number as 

abs (dCt1RefNum) -1. In a real desk accessory dCt 1RefNum is guaranteed to be neg- 
ative, so the unit name is calculated as -dCt LRefNum-1, but in the DA Shel] it’s 
dctlRefNum-1. 


Inthe DA Shell, your desk accessory will get a goodbye kiss synchronously 
(immediately). As a real desk accessory, it gets it asynchronously. 
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If you're writing a multi-segment desk accessory, and you want to use the DA Shell, you 
may need to define dummy versions of the A4 routines like this: 


unit DummyA4World; 

interface 
procedure SetUpA4; 
procedure RestoreA4; 
UnloadA4Seg(pPtr: ProcPtr); 


implementation 
procedure SetUpA4; 
begin 
end; 


procedure RestoreA4; 
begin 
end; 


procedure UnloadA4Seg(pPtr: ProcPtr) ; 
begin 
UnloadSeg (pPtr) 
end; 
end. 


Just add this unit to your project after your libraries. You don’t need to put the unit’s name in 
a uses Clause since the compiler will treat the procedure names as externals and resolve 
them at link time. 


Building Code Resources 


You can use THINK Pascal to write pure code resources. Code resources don’t have the 
complex structure of drivers; they simply contain code to be called at the entry point, the 
function or procedure main. 


You might want to write code resources for several reasons. You might want to write a win- 
dow definition function that you can use in several other programs, or you might want to 
write an INIT to run at startup. You may define your own code resource types to make a 
function you've written in THINK Pascal available to a program written in another language. 
The “client” program simply loads the resource and calls it at its beginning. 


This section tells you how to build code resources in THINK Pascal. The specific formats and 
calling sequences for code resources are given in the various volumes and chapters of Inside 
Macintosh. This list will help you get started. 


141 


THINK’s Lightspeed Pascal 


142 


To learn how to build a... 


ADBS resource 
CDEF resource 
cdev resource 
FKEY resource 
INIT resource 


LDEF resource 
MBDF resource 
MDEF resource 


WDEF resource 


Setting the project type 


Set the project type before you start working on a code resource. If you set the project type 
after you’ve started compiling code, you'll have to recompile your source files and reload 


your libraries. 


Choose Set Project Type.. 
Code Resource icon. 


Read Inside Macintosh... 


Volume V, Chapter 20, “The Apple Desktop Bus” 


Volume I, Chapter 10, “The Control Manager” 
Volume V, Chapter 18, “The Control Panel” 
Technical Note 3 (also see below) 


Volume IV, Chapter 29, “The System Resource File” 


Volume V, Chapter 19, “The Start Manager” 


Volume IV, Chapter 30, “The List Manager Package” 


Volume V, Chapter 13, “The Menu Manager” 
Volume I, Chapter 11, “The Menu Manager” 
Volume V, Chapter 13, “The Menu Manager” 
Volume I, Chapter 9, “The Window Manager” 


. from the Project menu. When the dialog appears, click on the 


a 


Application 


Desk Accessory 


Code Resource} 


File Information 


[2777 | Creator: 


Resource Information 


Fill in the Type and ID of the code resource you're building. If you like, you can give your 


code resource a name. 


Use the Attributes pop-up menu to set the resource attributes for your code resource. To 
learn about resource attributes, see Inside Macintosh I, Chapter 5, “The Resource Manager.” 


Building Projects 


If you check the Custom Header check box, THINK Pascal won't use the standard code re- 
source header to start the resource, See “Code resource headers” later in this section, 


Before you start working on your code resource, remove the default Runtime. 1ib library 
and replace it with the special DRVRRunt ime. 1ib library. This library is like 

Runtime. 1ib except that it does not contain the Pascal I/O routines. (This means that you 
can’t use writeln ina code resource, for instance.) 


How to write a code resource in THINK Pascal 

To write a code resource in THINK Pascal you must follow some rules. A code resource is 
composed only of units. It may not have a main program. Code resources can have only one 
segment. A code resource must have a unit that contains a function or a procedure called 
main, and that function or procedure must appear in its interface section. A code resource 
cannot have any global data. 


The way you write your main routine depends on the kind of resource you're writing. An 
FKEY, for example, is called by the Event Manager. It doesn’t have any arguments. You 
would define main like this: 


unit MyFKEY; 
interface 


procedure main; 
implementation 


procedure main; 
begin 
end; 

end. 


A WDEF resource is a custom window definition. The Window Manager calls main with sev- 
eral arguments and expects the window definition function to return a LONGINT. This is how 
you would write main for a WDEF: 


function main (varCode: integer; theWindow: WindowPtr; 
message: integer; param: longint): longint; 
begin 


end; 


Global data in code resources 


Code resources cannot have global data. You can take advantage of Pascal's nested proce- 
dures to simulate global data. Just nest all of the routines in your program within main. 
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Using libraries in code resources 


You can use libraries in code resources as long as the libraries don’t reference global vari- 
ables. For instance, you can’t use New and Dispose in a code resource because they use 
global storage. You cannot use Object Pascal in a code resource. 


Use the DRVRRunt ime. lib library instead of the default Runtime. 1ib library when you 
build code resources. 


Locking code resources 


The Macintosh Toolbox takes care of locking and unlocking the standard code resources like 
WDEFs. When you write your own code resources, you can either let the caller take responsi- 
bility for locking and unlocking them, or you can have the code resource do it itself. 


When main is entered, the low memory global ToolScratch contains a pointer to your 
code resource. If you need to lock it, you would write main like this: 


procedure main; 


var 
pp: “Ptr; 
h: Handle; 


begin 
pp := Ptr(S$09CE); { ToolScratch } 
h := RecoverHandle (pp*) ; 
HLock (h) ; 


HUnlock (h) ; 
end; 


Note: When the Toolbox uses an MDEF, it expects to find a certain value in 
ToolScratch, To write an MDEF, you'll have to use a Custom Header, de- 
scribed below. 


If your code resource can be called reentrantly, don’t unlock it unconditionally when it 
returns. Instead, restore it to the same state of locked-ness it had on entry. 
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Code resource headers 
When THINK Pascal creates a code resource it places this standard header at the beginning: 


Offset Contents 

0 BRA.S .+$10 (branch to header code) 
2 $0000 (unused) 

4 'TYPE' (resource type) 

8 $000A (resource ID) 

10 ($A) $0000 (unused) 

12 ($C) $0000 (unused) 

14 (SE) $0000 (unused) 


The standard header code puts the address of your code resource in Tool Scratch and 
then branches to your main routine. You can do anything you like with the unused words. 


If you check the Custom Header option in the Set Project Type... dialog, THINK Pascal 
does not generate this standard resource header. Instead, the file that contains main is guar- 
anteed to be the first file in the code resources. 


You can use this feature for writing resources that require special headers like PDEFs, The 


file that contains main should be written in assembly language. See Chapter 13 to learn how 
to write routines in assembly language for use in THINK Pascal. 
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Putting It Together 


When you're finished developing your application, desk accessory, device driver, or code re- 
source, choose one of the Build... commands in the Project menu, The actual name of the 
Build... command could be Build Application..., Build Desk Accessory..., Build 
Driver..., or Build Code Resource..., depending on the project type. When you choose 
one of the commands, you'll see a dialog box like this: 


Save Application as 


AboutBox 1.0423 
& Smart Link 


When THINK Pascal puts your final file together, it compiles all the files that need to be re- 
compiled. If you’re building an application, and you have the Debug option on, THINK 
Pascal recompiles all the files with the Debug option turned off. 


Note: THINK Pascal does not change any of the other compiler options 
during a build. You will probably want to disable Range and Overflow 
checking yourself. 


To make your final file as small as possible, THINK Pascal uses a technique called smart 
linking. THINK Pascal examines all the libraries and source files that your project uses. If 
there are files that your program doesn't reference at all, it doesn’t incorporate their code in 
the final file. For libraries, THINK Pascal includes only the routines that your program 
references, so there’s no penalty in using large libraries. 


Smart linking yields a smaller final application, but it takes longer to produce it. If you’re 
doing a lot of builds you might want to turn smart linking off. Just click on the Smart Link 
check box when you build your final file. 


After THINK Pascal links your program, it produces the application, desk accessory, device 
driver, or code resource file. At the end, it copies the resources from the resource file you 
specified in the Run Options... dialog into the final file. 


Assembly Language 


Introduction 


Most of the Macintosh Toolbox routines expect to be called from Pascal. The data types used 
by the routines are usually described as Pascal records, pointers, and arrays. That’s why 
working in Pascal on the Macintosh is a natural fit. 


Of course, deep inside the Macintosh works in MC68000 machine language. For some spe- 
cialized tasks, assembly language is the only way to get the job done. 


This chapter shows you how to use assembly language routines in your THINK Pascal pro- 
grams. It begins with an overview of the Macintosh software environment and a description 
of how Pascal data structures exist within that environment, Next is a description of Pascal 
calling conventions so you can be sure that your assembly language routines are well-be- 
haved. Finally, this chapter shows you how to use assembly language routines written in 
other development environments with THINK Pascal. 


Even if you don’t plan on writing or using assembly language routines in your programs, this 
chapter will give you enough background to help you use the built in LightsBug debugger as 
well as low level debuggers like TMON or Macsbug. 


What you should know 

This chapter assumes you know about MC68000 assembly language. But you don’t have to 
be a proficient assembly language programmer to understand this chapter. And although this 
chapter gives you an overview of the Macintosh software architecture, it doesn’t go into too 
much detail. To learn more about how the Macintosh manages memory and how it loads 
your program, read Inside Macintosh IT, Chapter 1, “The Memory Manager,” and Inside 
Macintosh Il, Chapter 2, “The Segment Loader.” 


If you plan to write assembly language routines to use in THINK Pascal, you can use THINK’s 
LightspeedC, Apple’s Macintosh Programmer’s Workshop, or the Consulair Development 
System. 


Topics covered in this chapter 
¢ The runtime environment 
¢ Pascal data types 
¢ Pascal calling conventions 
e Using assembly language 
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The Runtime Environment 


While your program is running, all memory is divided into three parts: the stack, the heap, 
and the A5 world, 


The Stack 


The stack is an area of memory that is dynamically allocated and deallocated in a strict last- 
in-first-out fashion, like a stack of trays in a cafeteria. The MC68000’s A7 register is reserved 
as a stack pointer. It always contains the address of the top of the stack. 


Note: The stack in the MC68000 actually grows downward, towards lower 
memory addresses, so the top of the stack is actually the byte in the stack 
with the lowest address. 


The stack contains information about the activation and deactivation of procedure and func- 
tions, Each time a routine is called, a stack frame is allocated. The stack frame contains all of 
the routine’s parameters, local variables and temporaries, and the return address. When the 
routine exits, the stack frame is released and the context of the calling routine is restored. The 
register A6 is the frame pointer of the currently active procedure or function. 


The Heap 


The heap (also called a zone in Macintosh terminology) is the area of memory that the 
Macintosh uses to allocate dynamic data structures like windows, menus, resources, the code 
for the program itself, and other heap zones. 


The Macintosh Memory Manager takes care of all the housekeeping chores. It knows where a 
new block can be allocated, what to do with deallocated blocks, and how to compact the 
heap when it needs space. 


The memory within a heap is divided into three kinds of blocks: 


* Free Blocks - these blocks represent unused heap memory that may be allocated to sat- 
isfy a memory request. 


* Non-relocatable Blocks - these are allocated blocks of memory that reside at a fixed 
location, They are referenced by a pointer to the block. 


¢ Relocatable Blocks - these are blocks that the Memory Manager can move around to 
make more room in the heap for larger blocks. Because a relocatable block can move, 
your application can’t keep a pointer to it. Instead, the Memory Manager maintains and 
updates a master pointer that points to the block of memory. The Memory Manager gives 
you a handle, a pointer to the master pointer, so you can access the block. To access a 
relocatable block, you dereference the handle twice. 


Assembly Language 1 


The Memory Manager is one of the fundamental parts of the Macintosh operating system. 
There is a great deal of myth and lore concerning its effective use. For more information, see 
Inside Macintosh Il, Chapter 1, “The Memory Manager” and Scott Knaster’s How to Write 
Macintosh Software. 


The A5 World 
The A5 world is a colloquial term for the area of memory that is referenced through register 


A5. The A5 world looks like this: 


application params 
ptr to QD globs 


application globals 


AS 


(AS) 


QuickDraw globals 


* The 32 bytes from the memory location specified in register AS contain the application 
parameters. This is information used and maintained by the system. The only part of 
this section you might use is 0(A5) which contains a pointer to the beginning of the 
QuickDraw globals. 


¢ Immediately following the application parameters is the jump table. The Segment 
Loader uses the jump table to load and unload segments of code. Every procedure and 
function that is referenced across segments has an entry in this table. For more informa- 
tion about the Segment Loader see Inside Macintosh II, Chapter 2, “The Segment 
Loader.” To learn how to break up your THINK Pascal program into segments, see 
Chapter 7. 


* The area of memory below AS is reserved for the application globals. All of the globals 


that your application defines are stored here, as are the QuickDraw globals. 


Pascal Data Types 


When you're writing an assembly language routine, you need to know how THINK Pascal 
stores the various Pascal data types in memory. 
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Integer Types 


Integers of type integer are represented as a 16-bit two’s complement number with a 
range of -32768 to 32767. 


Integers of type longint are represented as a 32-bit two’s complement number with a 
range of -2147483648 to 2147483647. 


Subranges of integer in the range -128 to 127 are represented in 8 bits number. Subranges 
with bounds outside this range occupy 16 bits. 


Note: If an integer subrange is in the range 0 to 255 and it is a component 
of a packed structured type, it is represented as an unsigned byte (8 bits). 


Chars 
The type char is represented as a 16-bit value with the extended ASCII code of the character 
in the low-order byte, and 0 in the high-order byte. 


Note: Ifa char is a component of a packed structured-type, it is repre- 
sented as an unsigned byte (8 bits). 
Booleans 


The type boolean is represented as a byte. It may assume only the values 0 (false) or 1 
(true), 


Enumerated Types 


Enumerated types are represented as unsigned bytes. They may assume ordinal values in the 
range 0 to 255 depending upon the number of enumerated constants in the type. 


Real Types 


The real-types real, double, and extended are represented as IEEE-format floating-point 
numbers of 32, 64 and 80 bits respectively. The real type COMPUTATIONAL is represented as 
a 64-bit two’s complement integer. 


Note; If you compile your program with the MC68881 option, extended 
values are 96 bits long. To learn more about the MC68881 option, see 
Chapter 15, 


The floating-point formats are described in complete detail in Apple Numerics Manual, 
Second Edition (Addison-Wesley) 
Pointers 


Pointer-types are represented as 32-bit address values. Only the low order 24 bits contain the 
address. The Macintosh Memory Manager uses the high-order 8-bits, and they are not 
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guaranteed to be 0. Use the Toolbox routine St ripAddress to turn a Memory Manager 
address into a canonical address before doing any pointer arithmetic. 


Strings 
A STRING of size n has a 1 byte length field followed by n bytes containing the character 


components of the string (each occupying a single byte as if packed). An unused byte is 
added to the end if needed to ensure that the total number of bytes is even. 


Arrays 


An array with index [L. .H] is represented as if H-L+1 variables of the component type 
were laid end to end. If the size of the component type is not 1, it is first rounded to an even 
number of bytes so that each element of the array is on an even byte boundary, An unused 
byte is appended to the array if necessary to ensure that it occupies an even number of bytes. 


A multidimensional array of indices [L1..H1, L2..H2, .., Ln..Hn] is represented as 
if it were declared as an array of index [L1..H1] with a component array of index 
(L2..H2] with a component array of index [L3. .H3], etc. 


A packed array is identical to the corresponding array type unless the component type is 
packable (i.e. CHAR or integer subrange in the range 0. . 255) in which case the components 
are allocated in their packed format. 


Records 


A record with fields £1: T1, £2: T2, .., fn: Tn is represented as if each field were a 
single variable and all fields were laid end to end. If a field’s size is not 1, the field is first 
aligned to an even boundary. An unused byte is appended to the rest of the record if neces- 
sary to ensure that it occupies an even number of bytes. 


A packed record is identical to the corresponding record type unless the types of one or more 
fields are packable (i.e. CHAR or integer subrange in the range 0. .255) in which case the 
fields are allocated in their packed format. 


Sets 


Sets are represented as bit arrays where each bit indicates whether the corresponding ele- 
ment is in the set or not. Sets occupy an even number of words, and are always allocated as if 
the set origin were 0: aset of 0..255 occupies the same number of bytes asa set of 
100..255. 


Note: A set with elements in the ordinal range 0. . 7 is stored as a byte. 
However, when passed as an actual value parameter, the set is first ex- 
tended to a word, so the value ends up in the low-order byte rather than the 
high-order byte. 
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Files 


A file is represented as a record of 58 bytes of status information followed by a compo- 
nent buffer whose size is equal to the size of the component type of the file. 


Files of type text are represented identically to packed file of char. However, the 
predefined routines eoln, writeln, and read1n can only be used with files of type text. 
See Section 9 of the Chapter 17. 


Pascal Calling Conventions 


Most of the Macintosh Toolbox routines expect to be called as if from Pascal. When you write 
your assembly language routines, be sure that they follow the Pascal calling conventions. 


Pascal calling sequence 


If the routine is a function, it is the caller’s responsibility to reserve space on the stack for the 
return value. The caller then pushes the arguments in left-to-right order and calls the func- 
tion. Upon return, the result (if any) may be found on the stack. The caller's code looks 
something like this: 


SUBQ #n, SP 7 reserve space for result 
MOVE ep (SP) 7 first argument 

MOVE wen (SB) ; last argument 

JSR routine 

MOVE (SE) Fa. 7 result 


If the called routine is a stack-based Toolbox trap, THINK Pascal generates the appropriate 
trap word instead of the JSR instruction. For all other routines, the compiler generates a JSR 
instruction. 


Note: For register-based traps, for routines dispatched through a single trap, 
or for routines marked [Not in ROM] the JSR goes to glue code in 
Interface.lib. 


If the called routine is in a nested scope, the caller also provides the static link, the frame 
pointer of the most recent activation of the nesting procedure or function, It’s very unlikely 
that any assembly language routines you write will need a static link. 


Pascal routine entry 


Just after the call to the Pascal routine, the return address is on the top of the stack. Most of 
the time, the routine will create a stack frame with the LINK instruction, and it will save any 
non-scratch registers. 
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As the routine begins, the stack looks like this: 


first argument 


last argument 


AG 


SP 


The function’s code looks something like this: 


LINK AG, #... 7; (optional) 
MOVEM.L .., -(SP) 7; (optional) save registers 
; code for the routine 


The last argument can be found at 8 (A6). If there was a static link, the last argument is at 
12 (A6). You can find the first local variable at a negative offset from A6. The value of the 
offset depends on the size of the variable. 


Note: You generally don’t need to worry about static links. 


All arguments occupy 2 or 4 bytes on the stack. A byte argument appears in the high byte of 
its word and is found at an even offset from A6. 


Pascal routine exit 


When a Pascal routine exits, it is responsible for deallocating its stack frame and for removing 
any arguments from the stack. So the end of Pascal routine looks like this: 


MOVEM.L (SP)+,.. - (optional) restore registers 
UNLK AG 7 ~~ ~=©(optional) 
MOVE (SP)+,A0 7 return address in AO 
ADD #...,5P 7 total size of arguments 
x including static link if necessary 
MOVE wp (SP) 7; store return result 
JMP (A0) 7; return to the caller 


153 


THINK’s Lightspeed Pascal 


154 


The code that THINK Pascal actually generates to return from a function may be slightly dif- 
ferent because the compiler optimizes the stack cleanup. If you have the MC68020 option on, 
for instance, THINK Pascal uses an RTD instruction to clean up the stack and return to the 
caller, 


Parameter passing 
The way you push parameters on the stack depends on the size and kind of parameter. 


For this kind of parameter... Do this... 
VAR parameters Push the address of the actual parameter on the stack. 
Value parameters If the size of the actual parameter is 4 bytes or less, 


push the value of the parameter. All values take up ei- 
ther 2 or 4 bytes on the stack. A byte value appears in 
the high byte of the word, and you can find it at an 
even offset from register SP or A6. 


If the size of the parameter is greater than 4 bytes, pass 
the address of the actual parameter. It is the caller’s re- 
sponsibility to make a copy of the parameter in case it 
is modified. 


Procedural parameters Push the address of the procedure or function, then 
push the static link to be used when the routine is ac- 
tually called. If the procedure or function is declared in 
the outermost scope, pass a 0 for the static link. 


Note: A procedural parameter is not the same thing as 
passing a pointer to a procedure or function. 


Return Values 


If the size of the return value of a function is 4 bytes or less, the caller allocates 2 or 4 bytes 
on the stack for it. When the function returns, this value is left on the stack. 


If the size of the return value is more than 4 bytes, the caller allocates a temporary variable of 
the appropriate size and pushes its address as a “hidden parameter.” When the function re- 
turns, the caller discards the address of the hidden parameter. 


Register saving conventions 

You can use registers D0, D1, D2, AO, and Al freely in your assembly language routines. If 
you need to use other registers, be sure to save and restore them. If the machine you're pro- 
gramming for has a MC68881 math processor, you can use registers FP0, FP1, and FP2. 
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Note: Because registers A5, A6, and A7 are used to maintain vital state in- 
formation between calls to subroutines, you should try to avoid using them 
except to access globals variables, local variables, frame pointers, etc. If you 
push something on the stack, be sure to pop it off. 


Using Assembly Language 


You can use THINK’s LightspeedC, Apple’s Macintosh Programmer's Workshop (MPW), and 
the Consulair Development System (CDS) to write assembly language routines that you can 
use in THINK Pascal. You can add THINK C libraries and MPW object files directly to your 
THINK Pascal project. If you use CDS, you'll need to use the conversion utility supplied in 
your THINK Pascal package to convert the object code into a THINK Pascal library. 


When you write a routine in assembly language, it’s up to you to make sure that you follow 
the proper Pascal calling conventions and that you call it correctly from Pascal. For example, 
suppose that you wrote a function, NewSysHandle, that creates a new handle in the system 
heap. The function takes a LONGINT that is the size of the handle, and it returns the new 
handle. To use the function, you would put this declaration in your Pascal program: 


function NewSysHandle(size : LONGINT) : Handle; 
external; 


The external directive tells THINK Pascal to look for NewSysHandle when it links your pro- 
gram. Presumably, the routine is in a library that you’ve added to your project. 


Using THINK’s LightspeedC with THINK Pascal 
To write the NewSysHand_le function in THINK’s LightspeedC, write it like this: 


pascal Handle NewSysHandle (size) 


long size; 
{ 
asm { 
move.1 size, dod ; Size of handle in do 
_NewHandle SYS 7 call the trap 
move.w do, 0x220 7; put result in MemErr 
move.1 a0, do 7 put return in DO for THINK C 


} 
The pascal keyword instructs THINK C to use Pascal calling conventions. This way, you 


can let the compiler worry about following the rules while you write the meat of your routine 
in assembly language (or, if you prefer, in C). 
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If you'd rather take care of managing the stack yourself, you can write the routine this way: 


NewSysHandle() 
{ 
asm { 

movea.1l (sp)+, al 7 get return address 
move.1 (sp)+, dod ; size of handle in dO 
_NewHandle SyS + call the trap 
move.w dO, 0x220 7 put result in MemErr 
move.1 a0, (sp) ; put result on stack 
jmp (al) 7; xeturn to caller 


} 


To use Pascal global symbols from THINK C source files, just declare them extern and use 
them as you would any other C symbol. 


After you compile the file, use the THINK C Build Library... command to create a library. 
Since you can load THINK C libraries directly into THINK Pascal projects, that’s all you have 
to do. 


To learn more about writing Pascal compatible routines in THINK’s LightspeedC, see 
Chapters 10 and 12 of the THINK’s LightspeedC User’s Manual. 


Using Apple’s Macintosh Programmer’s Workshop 


To write the NewSysHandle function with Apple’s Macintosh Programmer’s Workshop, 
write the assembly language file like this: 


INCLUDE 'SysEqu.a' 
INCLUDE 'Traps.a' 


NewSysHandle PROC EXPORT 
movea.1 (sp)+, al * get return address 
move.1 (sp)+, dod ; size of handle in d0 
_NewHandle sys 7 call the trap 
move.w dd, $220 7 put result in MemErr 
move.1 a0, (sp) *; put result on stack 
jmp (al) + return to caller 
ENDP 
END 


To access Pascal global symbols from MPW assembly language files, declare them external 
with the IMPORT directive and reference them from register A5 for applications or register 
A4 for desk accessories and device drivers. 
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Once you assemble the file, you can use the Add File... command to add an MPW object file 
to your THINK Pascal project. 


Using the Consulair Development System 


To write the NewSysHand1e function with the Consulair Development System, you write 
the assembly language file nearly the same way as with MPW: 


INCLUDE 'SysTraps.txt' 


XDEF NewSysHandle 
NewSysHandle: 

movea.1 (sp)+, al * get return address 
move.1 (sp)+, ad ; size of handle in d0 
_NewHandle ,SYS ; call the trap 
move.w do, $220 7 put result in MemErr 
move.1 a0, (sp) 7 put result on stack 
jmp (al) 7; return to caller 

END 


To access Pascal global symbols from CDS assembly language files, declare them external 
with the XREF directive and reference them from register A5 for applications or register A4 
for desk accessories and device drivers. 


After you assemble the file, use the .REL Converter utilityon disk THINK Pascal 1 
of your THINK Pascal package to turn the .Rel file into a THINK Pascal library. The . Rel 
Converter utility displays a standard file dialog that lets you choose the file to convert. 
When you click on the Convert button, the utility generates a THINK Pascal library with a 

. lib suffix rather than a . Rel suffix. 
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Introduction 


This chapter shows you how to use LightsBug, THINK Pascal’s powerful debugging tool. 
LightsBug lets you get a close-up view of your program. When you stop your program, you 
can see all the procedures and functions that called the routine you’re stopped in, the values 
of all the local and global variables, all the blocks in the application and system heaps, the 
MC680x0 registers, and any part of memory. 


What you should know 


LightsBug knows about things like procedures, functions, arrays, and records, and it knows 
about low-level Macintosh objects like heap zones. For an overview of the Macintosh 
Memory Manager, see Inside Macintosh I, Chapter 3, “Macintosh Memory Management: An 
Introduction.” To learn about the technical details of the Memory Manager, see /nside 
Macintosh II, Chapter 1, “The Memory Manager.” 


You'll find LightsBug more useful if you know something about memory organization and 
Pascal calling conventions. You can learn about these things in Chapter 13. 


Topics covered in this chapter 
* Using LightsBug 
¢ Subroutine call chain 
¢ Examining variables 
¢ Examining structured variables 
¢ Examining many variables 
¢ Using watchpoints 
* Type casting variables 
¢ Examining registers 
¢ Examining heap zones 
¢ Displaying memory 
¢ Editing memory 
¢ Debugging Toolbox routines 
¢ Examining compiled code 
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Using LightsBug 


LightsBug works best when you have both the Debug and the Names options turned on. To 
learn about these options, see Chapter 7 and Chapter 15. 


When you choose the LightsBug command from the Windows menu, you'll see a LightsBug 
window like this; 


EI LightsBug1 
HandleScrotl Lp ]Procedure HandleScrol 
>2222222? 20 delta : Integer 
Scro!|Content 20 pageSize : Integer 
HandleContent Integer 


23 part 


Hand | etlouse 2802.1. 


yo PBS 


Base: [iii] @) offset:[o000) (Edit) 
000: 4081 0000 4080 2A14 0006 DAE 0006 DAEA eA. .@A*.. 0h. Oj 
: 0006 DAGC 0006 DASE 0006 DA7O 0006 DA72 On. 

020: OO1E 2022 OO1E 2024 OO1E 2BA4 0006 DATA 
: OOIE 2028 OOIE 2028 OOIE 2028 OO1E 2028 


Beh fa] 


The LightsBug window looks more complicated than other THINK Pascal windows because 
it lets you work with a running program in several different ways. 


The LightsBug window is divided into four panes. The upper right pane and the middle 
pane can have different displays depending on how you use LightsBug. It may sound com- 
plicated, but once you experiment little, using LightsBug will become as easy as using other 
parts of THINK Pascal. 


The upper left pane always shows you the subroutine call chain. The upper right pane dis- 
plays subroutine variables, the MC68000 registers, and heap zones. The middle pane displays 
expanded views of variables, variables that you've put into a collected view, and watch 
points. The bottom pane always shows you the contents of your Macintosh’s memory, 


Working with panes 


To make a pane larger or smaller, drag the double line that separates the panes. To get rid of 
a pane altogether, drag the double line to the edge of the window. To get a pane back, just 
drag the double line back from the edge of the window. 


THINK Pascal lets you open up to four LightsBug windows. To create another LightsBug 
window, hold down the Shift key as you select the LightsBug command from the Windows 
menu. If there is more than one LightsBug window on the screen, choosing the LightsBug 
command cycles through all the open windows. 
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The LightsBug icons 


The icons along the left edge of the LightsBug window control the displays in the LightsBug 
panes. The icons are divided into three groups. 


OD LightsBug1 


Scrol |Content 20 pageSize : Integer 
register display [| Hand! eContent 23° part Integer 


Hand | eMouse 
Editor 


heap display 


expanded view 
collection 


watchpoint 


edit value 


Gal] @) offset :[0000 
: 4081 0000 4080 2A14 0006 DASE 0006 DAGA ef. .8A*.. 0h. . Oj 
: 0006 DASC 0006 DASE 0006 DA70 0006 DA72 ..Di Oh. Op. 
: OO1E 2022 OO1E 2024 OO1E 2BA4 0006 DATA 
: OOIE 2028 OO1E 2028 OO1E 2028 OOIE 2028 


typecast value 


trash 


The first group of icons controls the display in the upper right pane of the LightsBug window. 


D Variable display. When you choose this icon, the pane 
displays all the variables visible to the routine selected 
in the subroutine call chain, 


ee) Register display. When you choose this icon, the pane 
displays all the MC680x0 registers in hexadecimal. If 
you have the MC68881 option on, the pane also dis- 
plays the floating point registers. 


Bs Heap display. When you choose this icon, the pane dis- 
plays your application heap zone or the system heap 
zone. 


The second group of icons controls what you see in the center pane. These icons work like 
containers — like folder icons in the Finder. You drag values into them. 


Q Expanded view. When you drag a variable name from 
the variable display into this icon, the center pane dis- 
plays its value. If the variable is a structured type (a 
record, an array, or a set), the display shows you all the 
fields or elements. 
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Collections. This container is like the expanded view 
container, but it can hold more than one value at a time. 
You can place several different values here so you can 
track them all at once. 


Ee) Watchpoints. This container also holds several values at 


once. Whenever one of the watchpoints changes, 
THINK Pascal stops your program. 


The third group of icons lets you edit values. These icons work like filters. You drag some- 
thing into them and get something else. 


f Edit value. When you drag a value into this icon, 
LightsBug displays a dialog box that lets you edit the 
value. 

Bg Typecast value. When you drag a value into this icon, 


LightsBug displays a dialog box that lets you change the 
type of a value. For example, you can change a generic 
handle into a Cont rolHandle. 


The last icon is like the Trash icon in the Finder. It lets you remove values from any of the 
containers, 


By Trash. When you drag a value from any of the con- 
tainers — expanded view, collections, or watchpoints 
— to this icon, the value is removed from the container. 
Unlike the Finder, you can’t drag things out of the trash 
in LightsBug. 


Examining Subroutines 


The upper left pane of the LightsBug window is the subroutine call chain. It shows you the 
list of all the subroutines that are currently active — all the subroutines that have been called 
but haven't returned yet. The most recently called subroutine is at the top of the list. 


HandleScrol | 


Scrol |Content 
Hand! eContent 


Hand! eMouse 
Edi tor 
-ED| TOR 
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LightsBug does its best to find the names of the subroutines in the call chain, When the sub- 
routine is compiled with the Debug option on, and it is in an open window, LightsBug uses 
the full name of the routine. Otherwise, LightsBug uses the name stored in the code when the 
Names option is on. (See Chapters 7 and 15 to learn more about the Names option.) 


LightsBug uses a system of case conventions and prefixes to let you know how the sub- 
routine was compiled. 


Name Display Meaning 

MyProc_Name The subroutine is in an open editing window and was 
compiled with the Debug option on. 

MYPROCNA The subroutine is not in an open editing window, or the 


subroutine was compiled with Debug option off and the 
Names option on. 

22222222 The subroutine it is not in an open editing window, or 
the routine was compiled with the Debug option off, or 
the routine has been compiled with the Names option 


off, 
Prefix Meaning 
no prefix The subroutine is in an open editing window and was 


compiled with the Debug option on. 
- The subroutine is not in an open editing window and 
was compiled with the Debug option on. 


> The subroutine was compiled with the Debug option 
off. 
* There was a gap in the call chain. This usually happens 


when an assembly language routine uses register A6 in 
an unusual way. 


In the picture above, EDITOR is the program name. EDITOR called a procedure Editor 
which called HandleMouse which called HandleContent which called 


with the Debug option off. 


When a subroutine is called recursively, its name will appear more than once in the subrou- 
tine call chain. 
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Examining Variables 


When you select a subroutine name from the subroutine call chain, the upper right pane be- 
comes the variable display. This display shows you the names, types, and values of all vari- 
ables (including parameters and global variables) visible to the subroutine. 


= LightsBug! 


and le o Procedure HandleScrol! | 
322222222 20 delta : Integer 
Scrol|Content 20 pageSize : Integer 
HandleContent 23° part Integer 


Hand |eNouse 
Edi tor Giobai Variables 


%| BILO|> [al 


000: pgs wine 4080 2A14 0006 DAS 0006 DAEA eA, .eF*,..0h, .0j 
SP )o10: c006 DABC 0005 DAGE 0006 DA70 0006 DA72 i. .oh. 
020: OO1E 2022 OOIE 2024 OOIE 2BA4 0006 DATA 
030: OO1E 2028 OO1E 2028 OO1E 2028 OOIE 2028 


The variables are listed in alphabetical order. 


Variables and scope 


LightsBug displays all the variables visible to the selected subroutine according to Pascal’s 
scoping rules. Every variable you could reference in the selected routine appears in the vari- 
able display. If the selected routine is nested within another routine, you'll see the variables 
for the enclosing routine. 


The variables for each routine are separated by a dotted line. LightsBug tells you whether the 
routine is a procedure or a function. If the routine is a function, LightsBug displays its return 
value right under the name. 


Global variables appear at the end of the variable display. Since the display shows only the 
variables that are visible to the selected subroutine, you'll see only the global variables that 
are in units known to the subroutine. 
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Variable display formats 
LightsBug displays the value of a variable in the most natural format for its type: 


Variable type Display format 

INTEGER 12, -73 (decimal) 

CHAR 'F' or CHR(13) 

String 'A String' 

Enumerated, BOOLEAN TRUE, FALSE, RED, WHITE 
Pointer, Handle, Object 00031F36 (hexadecimal value) 
Array, Record, Set <array>, <record>, <set> 


If a character isn’t in the printable range, LightsBug uses the form CHR (n) so you can see its 
value. A carriage return, for instance, would be displayed as CHR (13), 


Note: When you click on a variable, the memory pane displays the memory 
it occupies. See “Displaying Memory” below. 


Examining Structured Variables 


When you double-click on a variable in the variable display, LightsBug displays its 
expanded view in the middle pane. If the variable is a structured type (a record, an array, or 
a set), LightsBug shows you all the fields of the record or all the elements of the array. For 
example, if you double-click on the value of a record, you'll see all the fields of the record 
and their values in the expanded view pane. 


This is what the LightsBug looks like if you double-click on the scrol1Bar variable in the 
variable display pane: 


LightsBug1 
HandleScrol | LS] Procedure HandleScro! | 

20 delta : Integer 
Scrol |Content 20 pageSize : Integer 
Hand! eContent 23 part Integer 


Hand |eMouse dle 
Edi tor é ntre.|Hand.|¢... 


Level 


ooo0000G 


E tr 
0008C382 contr !Owner WindowPtr 
<record> contr!Rect Rect 

255) contr Vi Byte 
23 contriHil ; Bute 


| fesse: [O?70CO} Offset: 
000: 9000 G000 0008 C382 FF OOES O11C OOFS 
: FF1? 0014 0000 001A 0000 20A4 0007 4B60 OD. 
: 0000 0000 0000 do00 o000 oOo0 8200 0014 
: 0000 OREO OOOR OOCS OOES OODS OOF? 0000 


The top line in the expanded view gives you the name of the variable and its type. If the 
variable is a handle or a pointer, LightsBug dereferences to its base type, as in the example 
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above. The top line also tells you the name of the routine and unit that your variable is de- 
fined in. 


Note: LightsBug dereferences generic handles and pointers as if they were 
of the type SignedByte. If you know the type of the object a generic pointer 
or handle refers to, you can use type coercion to display it. See “Type 
Casting Variables” below. 


The fields of records appear in declaration order, and the elements of arrays appear in order. 
The expanded view displays values the same way as the variable display, so if a record con- 
tains another record, its value is <record>. 


To see an expanded view of a field of a record, an element of an array, or a set, just double- 
click on it. The field or element's expanded view replaces the current expanded view. 


LightsBug remembers each time you expand a value. You can use the < and > keys to follow 
the chain of expanded views, For example, suppose you're looking at an event record in the 
expanded view. If you double-click on the where field of the event record, the expanded 
view displays it as a point. Pressing the < key would return you to the event record display. 
From there, pressing the > key would show you the point display. 
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Examining Many Variables 


The expanded view lets you see only one variable at a time. You can save a group of vari- 
ables in the collected views. To put a variable in the collected views, just drag it from either 
variable display or the expanded view to the collected view icon. When you click on the col- 
lected view icon, you'll see all the variables in the middle pane. 


EI LightsBug1 EB 


Procedure HandleScro! | 
20 


EA a delta : Integer 
Serol IContent 20 pageSize : Integer 
Hand|eContent 23° part Integer 
00074864. scro! | Bar. 
e: 
OOO74BF8 AppleMenu : MenuHand!e 
chr¢g> BS : Char 


@ HandleScroll ¢ Edi torTopLevel 


0008C376 > HindowPtr 
srecord> contriRect : Rect 
255 contriVis : Byte 
v 23 contriHilite : Byte 
ray) 60 contriValue : Integer 
9° 0 contriMin : Integer 
loc 233 contr IMax : Mw 
D 000020R4 contriDefProc : Handle 
ome | O0074BSC contr!Data : Handle 
00000000 contriAction : ProcPtr 
0 contrirfCon : Longint 
"contr iTitle 2 Str255 
Edi tNenu** = Menulnfo © Edi torTopLevel 
102 menuld : Integer 
-1) menuidth : Integer 
-1 > =menuHeight : Integer 
OQOOO1EDC = menuProc : Handle 
-255 enableFlags : Longint 
‘Edit’ menuData > Str255 
Offset: 


: 0000 0000 0008 C376 FFFF OOE8 O11C OOFS 
010: FF1? O03C 0000 OOES 0000 20A4 0007 4B5C 
020: 0000 0000 0000 0000 COCA 486E 8200 0014 
: 0000 ORES OOOA OO4C OOES OOSC OOF? 474E 


You can have global variables and variables from different procedures and functions in the 
collected view. As your program runs, variables that belong to some routines will go out of 
scope. When this happens, their entry in the collected view says no context. If your program 
enters that routine again, you'll see their full values. 


To remove a variable from the collected views, just click on the first line of the variable and 
drag it to the trash icon. 


Note: You can’t drag items out of the trash like you can in the Finder. 
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Using Watchpoints 


The watchpoints container is just like the collected views container. The difference is that 
whenever the value of a variable in the watchpoints container changes, THINK Pascal stops 
your program and displays a “thumbs down” next to the line where the change was detected. 
Usually, the “thumbs down” points to the line following the line that actually changed the 
value. 


To turn the watchpoints feature off, just drag the watchpoints to the trash. 


Use watchpoints to debug strange behavior in your program. For instance, suppose you have 
a pointer that somehow ends up pointing to the wrong thing while your program is running. 
If you put the pointer in the watchpoints container, your program will stop at the statement 
that’s changing the value of the pointer. 


To make the watchpoints feature work, THINK Pascal has to look at all the values in the 
watchpoints container after every statement to see if they’ve changed. This checking will 
make your program run significanuy slower. When you drag a variable to the watchpoints 
container, THINK Pascal makes a copy of it. After each step, it compares the current value of 
the variable to the saved value. If you drag large variables to the watchpoints container (for 
instance, an array that takes up 100K), you might find that THINK Pascal runs out of memory. 


Note: You can double-click on a value displayed in the watchpoints pane to 
see its expanded view. 
Editing Variables 


You can use LightsBug to change the values of variables. To change a value, drag the vari- 
able into the edit value icon (the pencil). You'll see a dialog box like this: 


E Edit 
FontSize 


fe = 


Current Value 


12 


New Value 


Enter a new value for the number in the 


range -3276?..32767 
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Type the new value of the variable in the New Value field, click on the OK button. LightsBug 
will change the value if it falls within the legal range of values. 


Type Casting Variables 


LightsBug lets you look at objects of one type as if they were objects of another type. This 
operation is called type casting. For example, /nside Macintosh defines a WindowPtr asa 
pointer to a GrafPort instead of as pointer to a WindowRecord. To examine the 
WindowRecord fields of a variable declared as a WindowPtr, you need to type cast it. 


To type cast a variable, drag it from the variable display or any view in the center pane to the 
type cast icon (the fake-nose-and-glasses mask). You'll see a dialog box like this: 


Type Cast —$—_— os 


TheWindow~* 


GrafPort 


Current Type 


WindowRecord 


New Type 


Enter a new type for the variable 


Type the new type for the variable in the New Type field, and click OK. LightsBug changes 
the type to the new type and displays its expanded view. 


Note: When you type cast a variable, the type of the original variable doesn’t change. What 
changes is the way it’s displayed in the expanded view. 


Examining Registers 


To display the values of the MC68000 registers, click on the cash register icon in the 
LightsBug window. The upper right pane becomes the register display. The values of the 
registers appear in the register display like this: 

AO=O000605CC 


if 

ai A1=00000160 D1=00074080 
| A2=00000000 D2=0008E04C 
A3=00074B68 D3=00000017 
A4=00076F98 D4=00000000 
V7 ||AS=0008CBEC 05=00000000 


DO=00000401 


Scrol |Content 
HandleContent 
Hand | eMouse 
Edi tor 
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If your Macintosh has a MC68881 floating point coprocessor, and you have the MC68881 op- 
tion on, the values of the floating point registers appear in the register display, too. 


When you select a register, the value of the register becomes the new Base for the memory 
display. (See “Displaying Memory” below.) Usually you'll want to select register A7 (the stack 
pointer) to see what's on the stack. 


Note: If you need to edit the values of the registers, use a low level de- 
bugger like Macsbug or TMON. Unless you know exactly what you’re doing, 
its not a good idea to change the values of the registers. Be careful. See 
“Examining Compiled Code” at the end of this chapter. 


Examining Heap Zones 


When you select the heap icon in the LightsBug window, the upper right pane becomes the 
heap display. The heap display lets you examine the pointers and handles allocated in any 
heap zone. To learn about heap zones, see Inside Macintosh I, Chapter 3 and Inside 
Macintosh If, Chapter 2. 


The heap display looks like this. 


:[074080 
Scroll |Content Free Prgble Hnd Lek Prg Ptr 
Hand! eContent (00'1628.000809,.030., 502. 01 


y BP OT40BC 000100 
panelerionss Pp 07414 000100 


The three buttons at the top of the pane let you choose which heap to display: 


Button Heap zone displayed 
Ss System heap 

A Application heap 

Cc Current heap 


You can also enter the address of a heap zone in the box next to the buttons. If you enter an 
address that’s not a heap zone or if the heap is damaged, LightsBug gives you an error 
message. 


Note: All values in the heap display are in hexadecimal. 


Unless you changed the heap zone with Set Zone (), the current zone will be the same as 
the application zone. 
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Right under the heap zone buttons you'll see a summary of what's in the heap: 


Heading Meaning 

Free total size of all free objects 
Prgble total size of all purgeable objects 
Hnd number of handles allocated 
Lek number of locked objects 

Prg number of purgeable objects 
Ptr number of pointer allocated 


After the summary, every line in the heap display describes each object in the heap. 


resource type 
resource ID 


pesounce file reference number 


@©HO Heap : [Ga 


H OO1EC8 000010 2 KSWP 0000 002 
H 011920 OOO00R 0 


*P O18CA4 000054 
F gispo00 oo0004 


| 
handle attributes 


8 = locked 
4 = purgeable 
2 = resource 


size of block 
base address of block 


type of block 


H = handle 

P = pointer 

F = free block 
* = locked 


To see the contents of an object in the heap, click on it. Its contents will appear in the mem- 
ory display. The next section tells you how the memory display works. 
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Displaying Memory 


The bottom pane of the LightsBug window is the memory display. Memory appears in 
hexadecimal starting at the memory location Base+Offset. An ASCII display of the same 
memory appears to the right of the hex display. 


Base: [wwaian] ©) offset:[o000] (Edit) 
oar ‘0000 0008 C382 FFFF OOE8 011C OOFS 
: FF1? 0014 0000 001A 0000 20A4 0007 4B60 
: 0000 0000 0000 0000 0000 0000 8200 0014 


: 0000 OREO OOOR OOCS OOE9 OODS OOF? 0000 


There are several ways you can choose which memory is displayed. They all involve chang- 
ing the base address or the offset. 


To display a certain location in memory, type in its address in the Base field and press the 
Return or Enter key. You can also specify an offset in the offset field. If you click on the + 
button, THINK Pascal adds the offset to the Base and resets the Offset to zero. 


Note: You can press the ~ key to undo changes you made to the Base or 
Offset field. 


To display an object in the heap, click on it in the heap display pane. If the object is a 
pointer, the pointer becomes the Base address. If the object is a handle, the dereferenced 
handle becomes the Base address. The offset is set to zero. 


To display the memory a register points to, click on a register value in the register display 
pane. The value of the register becomes the Base address, and the offset is set to zero. 


To display the memory a variable occupies, click on a variable in the variable display pane or 
in any of the views in the center pane. The location in memory that holds the beginning of 
the variable becomes the Base address, and the offset is set to zero. 


To see the frame pointer for a subroutine or function, click on its name in the variable display 
pane. The address of the stack frame becomes the Base address, and the offset is set to zero. 


You can use the mouse to change the offset field. If you click on any byte in the memory dis- 
play, it becomes the first byte displayed. The Base address doesn’t change, but the Offset is 
updated accordingly. If you hold down the Shift key as you click on a byte in the memory 
display, the first byte in the display slides to the point you clicked on. 


You can use the mouse in combination with the Shift, Command, and Option keys to deref- 
erence objects in memory. 


To dereference four bytes, hold down the Option key as you click on a byte in memory. The 
four bytes from the cursor become the Base address, and the Offset is set to zero. To doa 
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handle dereference, hold down the Option and Command keys as you click on a byte in 
memory. 


e LightsBug remembers the last eight changes to the base address. You can recall them 
with the < and > keys. 


Note: The offset field is sign extended (i.e. if you type in a minus sign fol- 
lowed by a hex number, it will compute the proper value). 


Editing Memory 


You can edit memory displayed in LightsBug. Be sure you know what you're doing before 
you change any byte in memory. 


To edit memory, click on the small Edit button in the memory display pane or type Shift-E. A 
small window appears on top of the memory display: 


iB (Enter )(Cancel) 1:20 


125Fec c:.. 


The Addr field displays the address of the memory you’re editing. Initially, this address is the 
same address as the base address of the memory display. 


The rectangles above the Addr field let you edit one, two, or four bytes at a time. The rectan- 
gles contain one, two, or four lines to indicate the number of bytes being edited. In this ex- 
ample the rectangle with two lines is selected, so the edit box displays the two bytes of 
memory starting at Addr. 


To edit memory just type a value in the box. When you are done typing you can click on any 
of the four buttons in the edit box: 


Button Action 

Enter This button causes the change to take effect. This 
changes memory at Addr to the value just typed. You 
can also use the Return and Enter keys. 


Cancel This button cancels editing mode. You can also use 
Shift-~. 
Next This button causes the change to take effect, and dis- 


plays the next byte, word, or longword of memory. You 
can also use the Tab key. 

Revert This button restores the edited value to what it was pre- 
viously. You can also use the ~ key. 
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On the right side of the editing box, memory is displayed in different formats, with a letter 
identifying each format. Some formats may not be displayed depending on whether you're 
editing one, two, or four bytes. 


Symbol Format 

c characters 

x integer 

L longint 

s signed byte 

U unsigned byte 


You can use the < and > keys to move through memory when you're in edit mode. These 
keys change the offset in the memory display by one, two, or four bytes. 


Debugging Toolbox Routines 


LightsBug can also help you debug calls to Macintosh Toolbox routines, If you want to stop 
at every Toolbox call, choose the Break at A-Traps option in the Debug menu. When this 
option is on, your program will stop just before it executes a Macintosh Toolbox routine. 
When your program stops, it will look something like this: 


Show Edit 


[ 
procedure AdjText; {(winfo : WinfoHandle) } 
var 
oldScroll, newScroll, delta: integer ; 
begin 
with winfo™, teh** do begin 
oldScroll = viewRect.top - destrect.top; 
newSeroll := GetCtlValue(yScrollBar) * lineHeight; 


O LightsBug1 2 
{j])A2=00000000 D2=00000000 
AZ=00078CFS 03=000000 17 
R4=000766EC D4=00000000 
[if J85=0008CBEO D5=00000000 
AB=0008BF72 D6=00000000 
Keene 07=00000000 


Serol|IContent 
Hand|eContent 


Base: [EERE] G) offset :[0000 
000: 0007 4864 3DC2 0007 4864 0007 GS6EC FFFF ..Kd=4..Kd. -fooo 
O10: ?FFF 041D 0008 BF96 0400 OA24 0008 30C2 of, 

020: 0008 BFS4 0008 BF96 0007 C7F4 0007 4B7C 
030: 0000 0000 0014 0014 0008 BFF2 0700 1C54 
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A special execution finger with an A emblazoned on it points to the Toolbox routine your 
program’s about to execute. The LightsBug window shows you trap number in the subrou- 
tine call chain. 


LightsBug automatically chooses the register display and selects register A7 so you can see 
the contents of the stack in the memory display. In the example above, GetCt1Value takes 
a Cont rolHandle as an argument. The handle in this case is $74B64. 


Note: If you are executing code that was compiled with the Debug option 
off, the special execution finger may point to the same statement for many 
distinct A-Trap breaks. 


Examining Compiled Code 


A special mode of the Step command lets you use a low level debugger like TMON or 
Macsbug to examine compiled code. To examine the compiled code for a particular state- 
ment in your program, hold down the Shift key and choose the Step command from the Run 
menu. Instead of executing the next statement, THINK Pascal will drop into the low level de- 
bugger just before the RTS instruction that leads to your code. 


To examine your compiled code in TMON, choose the Step command and open an assembly 
window anchored to the PC. In Macsbug, type T, then IL PC to display the code. If you com- 
piled your program with the Names option on, you'll see the name of the subroutine in the 
low level debugger. When you're through examining the code, just choose the Exit com- 
mand in TMON or the G command in Macsbug. 


Note: If a low level debugger is not installed, holding down the Shift key 
with the Step command is the same as choosing Step from the Run menu, 
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Introduction 


This chapter describes the compiler directives you can you use in your THINK Pascal pro- 
grams and the options you can set to control code generation. A compiler directive is an 
instruction that tells the compiler how to compile a specific file or part of a file. 


You've already seen some of the THINK Pascal compiler directives as compiler options in 
the project window — the four letters D, N, V, and R. In this chapter you'll learn more about 
what these directives do and how you can control them from within your source code. You'll 
also learn about other directives that not only let you control how THINK Pascal compiles 
your source files but also what part of your source files it will compile. 


Topics covered in this chapter 
e What are compiler directives? 
¢ Using compiler directives 
¢ Using conditional compilation 
¢ Using the Compile Options command 
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What Are Compiler Directives? 


You're already familiar with four compiler directives from Chapter 7. These are the four let- 
ters in boxes in the Options column of project window. These compiler options control 
code generation for the file. When you add files to a project, the D and N options are already 


on. As you work on your program, you can turn the options on and off for specific files. 


To disable an option, simply click on the appropriate box. The box disappears. To enable the 


Interface .lib 8104 
Runtime.lib 18072 


(INI) Editor Globals oO 


[R] Editor Init 1266 


Sao Show Edit 1018 
aa 


[R] Change Font 1938 
[R] Editor Utilities 5746 


era Editor TopLevel 8368 
[DIMI] Editor Main 


Meaning 

Debug. Generates additional information between each 
Pascal statement to support stepping, stopping, and 
observing. 

Names. Inserts the name of all routines (truncated to 
eight characters) into the code. This is useful for debug- 
ging with LightsBug and Macsbug. 

Overflow Checking. Generates code that checks for in- 
teger arithmetic overflows. 

Range Checking. Generates code that does range 
checking for array indexing, assignments, and parame- 
ter passing. It also generates code that checks for nil 
pointer dereferencing. 


option again, click on the letter. The box reappears. 


Note: If you hold down the Option key as you click on a compiler option, 
THINK Pascal will change the option for all the files in the project. 


178 


Compiler Directives 15 


Using compiler directives in your source files 


You can also turn these compiler options on and off from your source file. When you use the 
compiler options in your source files, they are called compiler directives because they direct 
the compiler to generate different code. In addition to the four directives you can set as com- 
pile options, THINK Pascal provides two more. 


A compiler directive looks like this: 


{$D+} 

A compiler directive is a comment that begins with a $. The text after the $ specifies which 
directive and whether it’s on or off. In this example, D+ means that you want to turn the set- 
ting on. A minus sign would mean that you want the setting off. 


These are the six directives that THINK Pascal supports 


Directive Meaning 

{$D+} or {$D-} Turn Debug option on or off 

{$N+} or (SN-} Turn Names option on or off 

{$V+} or {$V-} Turn Overflow checking option on or off 

{$R+} or {$R-} Turn Range Checking option on or off 

{$I+} or {$I-} Turn automatic initialization on or off (only in main 
program) 

{SA+} or {$A-} Turn special handling for asynchronous procedures on 
or off 


THINK Pascal ignores any other directives. 


Note: The MPW Pascal { $D+} directive corresponds to the THINK Pascal 
{ SN+} directive, not the THINK Pascal {$D+} directive. Some MPW direc- 
tives don’t have analogous directives in THINK Pascal. 


The first four directives correspond to the four compile options in the project window, The 
difference is that the embedded compiler directives let you control code generation at the 
procedural level or even the statement level. For example, one common technique is to turn 
off the {$R} option when you want to change the length byte of string: 


{$R-} 
myString[0] := 0; { pretend it’s a null string } 
{$R+} 


To use a compiler directive, you put it right before the line you want to affect. 
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Ifa compile option — D, N, V, or R— is turned off for a file in your project, you can’t turn it 
back on with a compiler directive in your file. In other words, the compile options in the 
project work like a “master switch” for the compiler directives in your file. 


If you use the Debug, Name, or Asynch directives, you must change their state before the first 
begin of a procedure or function, or they won't have any effect until the next procedure or 
function. For example: 


{$D-} 

{ Don’t generate debugging code for this procedure } 
procedure SalmonSushi; 

begin 


end; “ 
{ $D+} 


But this won’t work: 


procedure Pakora; 
begin 
{$D-} 


end; i 
{$D+} 


THINK Pascal will still generate debugging code for procedure Pakora. 


How compiler directives work 


When you turn on one of the D, N, V, or R compiler directives, THINK Pascal weaves 
“invisible” code into your program. For example, the D directive inserts code that lets THINK 
Pascal know what your program is doing, so you can use its powerful debugger. Other op- 
tions, V and R, for instance, insert error checking routines to check for overflow or out-of- 
range conditions. When you turn on more than one option, you get the extra code for each 
option. 


When you change a compile option for a file, THINK Pascal recompiles the file to generate 
the new code before you run. 


Using Compiler Directives 


This section describes each compiler directive in detail. You'll learn exactly what the directive 
does and when you should use it. Since every compiler directive generates extra code, you'll 
also learn what it costs you — in terms of speed and memory — to use the directive. 
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Debug {$D+} 


When you turn the Debug option on, THINK Pascal generates code that lets you use all of the 
THINK Pascal debugging features. This code makes it possible for THINK Pascal to display a 
thumbs-down icon next to an error that occurs while your program’s running. For example, if 
your program tries to divide by zero, or tries to write beyond the end of a file, or tries to as- 
sign an out-of-range value to a variable, the debugging code lets THINK Pascal know which 
file and which line contains the error. 


This directive also generates code that looks out to make sure your stack doesn’t collide with 
the heap. If the stack were to run into the heap, you’d get a System Error ID=28. Or at least 
the error would damage the THINK Pascal environment, and you’d have to reboot and start 
again. Typically, these errors are hard to track down. 


The debugging directive acts as a kind of safety net, so it’s a good idea to leave this option on 
while your program is still unstable. 


If you use the {$D+} directive in your source code, be sure to put it before the first begin of 
the procedure you want to affect. 


Cost The Debug directive increases your code size by about 
30%. Your program runs 2 to 10 times slower. 


Limits You can’t have the Debug option on in a standalone 
application or in a library. When you choose one of the 
Build... commands from the Project menu, THINK 
Pascal turns the Debug directive off automatically. 


Uses If you plan to use a low-level debugger like TMON or 
Macsbug to debug a piece of code, it’s best to turn the 
Debug directive off so the additional debugging code 
doesn’t get in your way when you look at the assembly 
language listing. 


Names {$N+} 

The Names directive embeds the first eight characters of the subroutine name into the code 
right after the end of the procedure or function. LightsBug uses this name when the source 

file that contains the routine isn’t open. Other low-level debuggers like TMON or Macsbug 

use these names as well. 


Cost Eight extra bytes per procedure or function. No speed 
penalty. 
Limits The Names directive limits names to eight uppercase 


characters. Underscores are stripped off. If the name 
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takes up less than eight characters, the remaining bytes 
are filled with spaces. 


Uses Turn the Names option on whenever you're using 
LightsBug, TMON, or Macsbug to help you find you way 
around your routines, It’s usually a good idea to turn 
this option off before you create your final release. 


Overflow {$V+} 


The Overflow directive generates code that detects errors resulting from numeric overflow in 
arithmetic operations. The result of each intermediate operation must be within the bounds 
of numerical representation. For type INTEGER, the bounds are -32768 to +32767. For type 
LONGINT, this range is -2147483648 to +2147483647. 


For example, consider this procedure: 


procedure Boom; 


var 

i, 3, k : INTEGER; 
begin 

i := 20000; 

j := 21000; 

k:= it j; 
end; 


You might expect thatk = 41000, but since the largest integer is 32767, k would overflow 
(-24536), and you’d have an error. If the Overflow directive is on, THINK Pascal will catch 
this kind of error, 


The Overflow directive doesn’t check floating point operations, but the SANE library does. 
The SANE environment lets you control the effects of overflow in floating point operations. 
See the Apple Numerics Manual, Second Edition to learn more about SANE, 


Cost Two extra bytes generated for every arithmetic expres- 
sion. Your program runs 5% to 10% slower. 


Limits The Overflow works best while your program is still 
under development, and you're still working in the 
THINK Pascal environment. You can examine the vari- 
ables that caused the overflow and correct their values 
in the Observe or LightsBug windows. In a standalone 
program, recovery is more difficult, if not impossible. 
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Uses Use the Overflow directive to track down potential 
problems and to make sure that your program deals 
with errors appropriately. 


Range {$R+} 

The Range directive makes sure that values fall within legal bounds. For variable assignment, 
this directive checks that a value assigned to a variable is in the legal range for the variable. 
For instance, when your program assigns a value to a variable of type INTEGER, it makes 
sure that the value falls in the range +Maxint (432767). 


The Range directive also makes sure that the index of an array falls within the bounds of the 
index type. For instance, suppose your program contains this declaration: 


var 
SomeArray : array [1..25] of INTEGER 


The Range Checking directive would catch an illegal error like: 


SomeArray[27] := 1961; 


Note: If the index is a constant, the Range directive catches the error at 
compile time. Otherwise, it catches the error while the program is running. 


Strings are a special case. When the Range directive is on, it makes sure that the character be- 
ing accessed is in the range of the string’s current length. For example: 


type 
s25 = string[25]; 
var 
MyString : s25; 
begin 
MyString := 'abc'; 
MyString[4] := x; { ERROR. } 


end; 
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In fact, the most common use the of the { $R+} directive is to turn it off while your program 
manipulates strings. For instance, if you wanted to write your own version of the predefined 
Length function, you’d have to write it like this: 


{$R-} 
function MyLength (s:string): integer; 
begin 
MyLength:= ord(s[0]); {Compiles ONLY if Range option is off} 
end; 
{$R+} 


For more information about how THINK Pascal deals with strings, see Section 4.3.1 of 
Chapter 17. 


Finally, the Range directive checks to see if a pointer is nil before it dereferences it. The di- 
rective won't keep you from dereferencing an odd or invalid pointer, though. 


Cost Four to 24 bytes extra code generated for assignments, 
array accesses, and pointer dereferences. Your program 
runs about 10% to 20% slower. 


Limits Like Overflow checking, Range checking is easy to fix 
while you’re still in the THINK Pascal environment. 
Error recovery is difficult and impractical in standalone 
programs. 


Uses Turn the Range Checking directive on while your pro- 
gram is still under development. You'll probably want 
to turn it off when you want to manipulate strings 
directly. 


Initialization {$I+} 


As mentioned in Chapter 12, THINK Pascal usually takes care of initializing all the Toolbox 
managers for you. You can use the Initialization directive to turn this feature off if you prefer 
to initialize the managers yourself. The {$I+} directive tells THINK Pascal to initialize the 
managers automatically. The { $I-} directive lets THINK Pascal know that you're going to 
handle the initializations. 


When the Initialization directive is on, THINK Pascal calls these Toolbox routines: 


184 


Compiler Directives 15 


InitGraf InitDialogs 
InitFonts SetApplLimit 
InitWindows MaxApp1Zone 
InitMenus MoreMasters (10 times) 
TEInit 


The {$I-} directive should appear before the begin of your main program. THINK Pascal 
ignores this directive in units. 


Note: THINK Pascal never does automatic initialization for desk accessories, 
device drivers, or code resources. 


You'll usually use the {$I-} directive when you port Pascal code that contains the Toolbox 
manager initializations. 


If you checked the MC68881 option in the Compile Options... dialog, THINK Pascal also 
initializes the MC68881 state. This means that if you want your application to check for the 
68881, you should turn the Initialization directive off. Otherwise, your program will crash at 
startup on a machine that doesn’t have a MC68881. To learn more about the MC68881 op- 
tions, see “Using the Compile Options Command” at the end of this chapter. 


To initialize the MC68881 state yourself, use this procedure: 


procedure InitFPState; 


inline 
$42A7, i sie oe -(sp) } 
$42A7, {\ .ella..1 -(sp) } 
SF21F, $9800; { fmovem.1 (sp)+, fpcr/fpsr } 


Asynch {$A+} 

The Asynch directive helps you write asynchronous procedures like completion routines or 
vertical retrace tasks. An asynchronous procedure can run any time, even when the value of 
register A5, the pointer to your global variables, is wrong. 


When you turn the Asynch directive on, THINK Pascal generates code that saves the value of 
A5 and sets AS to the value of the low memory global CurrentA5 when your procedure 
starts. 


Note: When you use the Asynch directive, THINK Pascal turns the Debug 
directive off temporarily. 


The Toolbox routines SetUpAS5 and RestoreAS do the same thing, but the Asynch direc- 
tive gives you a more elegant way of setting up the AS world for your procedure. 
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Using Conditional Compilation 


The compiler directives described above let you control how THINK Pascal generates code in 
specific instances. The conditional compilation directives, though, let you generate differ- 
ent code for different circumstances. For instance, while you’re debugging your application, 
you might want to have additional debugging menus or particular routines that help you see 
what your application is doing. Or you might want to create two versions of your application: 
one that runs on any Macintosh and another one that runs only on a Macintosh with a float- 
ing point processor. 


The four conditional compilation directives are: 


{S$SETC identifier = expression} 
{$IFC expression} 

{ SELSEC} 

{ SENDC} 


These compiler directives work like Pascal statements. An identifier can be any legal Pascal 
identifier. An expression can consist of identifiers, integer constants, boolean constants and 
these operators: +, -, *, DIV, MOD, =, <>, <=, >=, <, >, AND, OR, NOT. 


An expression can also be of the form UNDEFINED identifier. This expression evalu- 
ates to TRUE if the identifier is undefined and FALSE if the identifier is defined. 


To find out which compiler options are set, use the OPTION (optionName) function. The 
argument can be one of MC68881, MC68020, DEBUG, RANGE, OVERFLOW, or NAMES. 


The { $SETC} directive lets you set values to compile-time variables. These are not vari- 
ables that you can use in your program. Instead, you use the variables to define conditions. 


Note: You can use := as well as = ina {$SETC} directive. 
By combining compile-time variables with the {$IFC}, {SELSEC}, and {SENDC} direc- 
tives, you can tell THINK Pascal which parts of your program you want it to compile and 


which parts you want it to ignore in specific cases. 


Here's an example. Suppose that you were writing an application that had a special menu 
that you wanted on only during development. You might write this: 


Compiler Directives 5 


program Toast; 
{$SETC development = TRUE} 
const 

FileMenuID = 1; 


{SIFC development } 
DebugMenuID = 7; 
{ SENDC} 


procedure StartMenus; 
var 
h : MenuHandle; 


begin 


{SIFC development } 
h := GetMenu (DebugMenu) ; 
InsertMenu(h, 0); 

{ SENDC} 

end; 


Note: In an actual case, you would probably set the value of the compile- 
time variable development with the Compile Options... command de- 
scribed in the next section. 


You can use conditional compilation directives anywhere in your source file, even in con- 
stant and type declarations. If you use a {$SETC} directive in a unit, you'll be able to use it 
in any file that uses the unit. 


Using the Compile Options Command 


The Compile Options... command in the Project menu lets you predefine symbols that 
you can use for conditional compilation as well as set up some other code generation 
options. 
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When you choose Compile Options... from the Project menu, you'll see this dialog box: 


Compile Options 


Compile-Time Variables Code Generation 


THINK_PASCAL=TRUE; 1 Mce6sss1 
Elems881=TRUE; — Mc6so20 


SET OF Integer 
@ 0..255 
© -32768 .. 32767 


Cancel 


Compile-time variables 


You can define any compile-time variable in the text-edit box in the left side of the dialog just 
as if you had typed: 


{SSETC identifier = value} 


THINK Pascal predefines two compile-time variables for you, THINK_PASCAL and 
Elems881. Use the THINK_PASCAL compile-time variable when you need to know if your 
program is being compiled by THINK Pascal. 


The Elems 881 compile-time variable is used by the SANE. p interface file to indicate that it 
should use the faster (but less accurate) transcendental functions built into the MC68881 math 
coprocessor if the MC68881 option is on. If you set the ELems8 81 compile-time variable to 
FALSE, THINK Pascal will use the slower, but more accurate, software versions of the tran- 
scendental functions. 


Compiler Directives 5 


MC68881 option 


When the MC68881 option is on, THINK Pascal generates code for the floating point proces- 
sor for all floating point operations. 


Note: THINK Pascal doesn’t check to see whether the machine you're writ- 
ing your program on or whether the machine your application runs on has a 
MC68881 coprocessor. Use the Toolbox routine SysEnvirons to check the 
features of the Macintosh you’re program is running on.. 


With this option on, you should use the SANE881.1ib version of the SANE library. This li- 
brary uses the same SANE. p interface file as the regular SANE. Lib. 


THINK Pascal generates direct calls to the floating point processor for some arithmetic func- 
tions. For other functions it uses library routines in the SANE library. This section tells you 
how THINK Pascal generates code for certain cases. To learn how to use the SANE routines, 
see Apple Numerics Manual, Second Edition (Addison-Wesley). 


These functions are built into THINK Pascal and generate direct calls to the floating point 
processor when the MC68881 option is on: 


ARCTAN LN 
cos SIN 
EXP SQRT 


These functions are in both SANE libraries and use the floating point processor when you use 
SANE881.1ib: 


EXP1 LOG2 
EXP2 TAN 
LN1 


These functions are built into THINK Pascal and generate direct calls to floating point 
processor when the MC68881 option is on. They are not in SANE. 1ib or in SANE881.1ib. 


ARCOS EXP10 
ARCSIN LOG10 
ARCTANH SINH 
COSH TANH 


Note: If you try to use these routines when the MC68881 option is off, you 
will get link errors. 
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If the Elems881 compile-time variable is set to TRUE and the MC68881 option is on, THINK 
Pascal does not generate direct calls to the floating point processor for the following routines. 
Instead it uses slower, but more accurate software versions in SANE8 81. 1ib: 


ARCTAN LN 
cos LN1 
EXP LOG2 
EXP1 SIN 
EXP2 TAN 


Note: The floating point processor's built-in routines for these functions 
comply with IEEE accuracy standards, so they should be adequate in most 
cases. The versions in SANE881.1ib comply with Apple’s more stringent 
standards, but can run over 100 times slower. 


MC68020 option 


When the MC68020 option is on, THINK Pascal generates code for the MC68020 CPU found 
on the Macintosh II and accelerator boards for other Macintosh computers. Specifically, 
THINK Pascal uses MC68020 instructions for 32 bit multiplies and divides and the RTD in- 
struction to strip arguments off the stack. 


Set of integer option 


THINK Pascal lets you specify whether sets of integer include all integers 

(-32768. . 32767) or just to the range 0. . 255. Most of the time, you'll use the smaller set 
range. The larger set range takes up considerably more space in your program and takes 
much longer to access than the smaller range. Sets of the range 0. .255 can take up al most 
32 bytes. Sets of the range -32768. . 32767 can take up to 8192 bytes. 
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Introduction 


This chapter describes each of the THINK Pascal menu commands. It is organized by menu, 
from left to right along the menu bar. Within each menu, commands are described in the or- 
der in which they appear in the menu. 


The Apple Menu 


* 
About THINK Pascal... 


About THINK Pascal... 
This command tells you what version of THINK Pascal you're using in an entertaining dis- 
play. Click the mouse to end the display. 
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The File Menu 


Use the File menu commands to work with files 
that you open and edit with the THINK Pascal 
editor. This menu also has commands that let 
you launch other applications and that let you 
quit THINK Pascal. 


Save As... 
Save a Copy As... 


Revert 


Page Setup... 


Delete... 


Transfer... 
Quit 


New 


This command opens a new Untitled Pascal edit window. Use the Save As... command to 
save new files. 


Open... 


This command lets you open an existing Pascal file in an edit window. You can have up to 
eight files open at once. You can also use this command to open Instant and Observe win- 
dows that you’ve saved. 


Close 


This command lets you close the active window. If you try to close an edit window, and the 
file has been modified since it was last saved, THINK Pascal will ask you if you want to save 
the changes, discard them, or cancel the Close command. 


You can’t use this command to close the project window. Use the Close Project command 
in the Project menu to do that. 


Note: When you click in an edit window’s close box, THINK Pascal hides 
the window without closing the file. To close the file, use this command or 
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hold down the Command key when you click in the window's close box. 
When you hold down the Command and Option keys together as you click 
in the close box, THINK Pascal closes all the files. 


Save 
This command saves the file in the active edit window to disk. This command is dimmed if 
the current edit window is untitled. 


Save As... 

This command lets you save the current file under another name. If you have made edits in 
the current session, they will be saved under the new name. The original file will remain un- 
changed, and as you continue editing, you will be editing the new file. This feature is useful 
for switching to a new version of a file, leaving the old file as a backup. 


The Save As... command tries to preserve the tie between the file you're editing and its entry 
in the project window. If the file is in the project window, THINK Pascal changes the name of 
the file in the project window to the new name. This command won't let you overwrite a file 
that’s already in the project window. 


When you choose this command, you'll see a standard save dialog box with two additional 
radio buttons. When you choose Text Only, THINK Pascal saves the file as a text file that you 
can open with any text editor or word processor. When you choose Entire Document, ‘IHINK 
Pascal saves the file in a special format that loads faster and preserves any Stop signs you've 
set in the file. 


G TextEd Demo 


Change Foat 
EdRor biobats 
Editor lak 

>} Editor Main 
Editor Project 
Editor Toplevel 


Save ‘Bullseye.p' as 


Editor Extras 


@Text Only 
© Entire Document 


You can use Save As... to save the Instant and Observe windows to a file. When either of 
those windows is the active window, you can use the Save As... command to save them. 
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Save a Copy As... 


Unlike Save As..., this command does not affect the status of the file currently being edited; 
it simply snapshots it to another file. This is a good way to make backups without finding 
yourself editing the backup! Save a Copy As... will not let you overwrite a file that’s already 
in the project window. 


Revert 


This command restores the last-saved version of the current file, discarding any edits made 
since the last Save or Save As.... 


Page Setup... 


This command displays the standard Page Setup dialog that lets you specify the size of the 
paper you're printing on, and whether the file should be printed upright on the page (tall 
orientation) or sideways (wide orientation). See your Macintosh owner's manual for details. 


Print... 


This command lets you print the current file. The standard Print dialog box lets you set the 
page range among other options. When you press the OK button, your file will begin to 
print. Each page of the file has a header showing the name of the file and the last modifica- 
tion date. To cancel printing , press Command-Period. 


Note: If the active window is the project window, the Print... command 
prints the project window. 

Delete... 

This command lets you delete a file from your disk without leaving THINK Pascal. 


Transfer... 


This command lets you launch another application without first returning to the Finder. 
When you’re running under MultiFinder, this command launches applications without quit- 
ling THINK Pascal. 


Quit 
This command quits THINK Pascal and returns to the Finder. 
If you choose Quit while a project is open, it will automatically be closed. If any editing win- 


dows have been modified, it will ask if you want to save or discard your edits, or cancel the 
Quit command. 
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The Edit Menu 


The Edit menu has the standard Macintosh edit- 
ing commands (Cut, Copy, Paste) as well as 
commands that let you specify how THINK 
Pascal should format your pascal source files. 


Source Options... 
Auto-Reformat 


Undo 


The Undo command reverses the last edit operation. The actual name of this command 
changes to let you know exactly what operation you'll be undoing. After a Paste, for instance, 
the name of this command changes to Undo Paste. Once you've undone something, the 
name of this command changes to Redo. 


If there isn’t anything to Undo, this command will be dimmed. If the operation to undo 
doesn’t belong to the frontmost window, the name of the command will indicate that there is 
something to do, but the command will be dimmed. 


You can’t undo a Replace All, or a Revert. 


Cut 


This command removes selected text and places it in the Clipboard. It replaces the current 
contents of the Clipboard (if there are any). Use the Paste command to insert text from the 
Clipboard into your file at the insertion point. 


Copy 
This command copies the selected text and places it in the Clipboard. The copy can now be 
pasted somewhere else using the Paste command. 


Paste 


This command copies the contents of the Clipboard into the file being edited at the insertion 
point. If text is currently selected, it is replaced. 
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Clear 


This command clears the selected text. The selection is not placed on the Clipboard. The 
Clear key on your keyboard has the same effect as the Clear command. 


Select All 
This command selects all the text in the current edit window. 


Source Options... 

The Source Options... command lets you change the way the THINK Pascal editor pretty- 
prints your source code. You can also change the tab spacing, the indentation spacing, and 
the font that the editor uses to display your file. Chapter 6 explains this command in more 
detail. 


When you select the Source Options... command, you'll see a dialog box like this: 


Source Display Settings 


1 | 


writeln('sum = ', sum); 
end. 


C 
Parameters 
el 


The four icons along the left let you choose different aspects of the formatting you can 
change with this command. When you click on the OK button, any changes you made in any 
section of this dialog will apply to your project. Clicking on the Save Settings button saves the 
settings as the THINK Pascal defaults. 


Fonts The pop-up menu lets you choose the font and size that THINK 
Pascal uses to display your source file. 


Keywords This option lets you choose how THINK Pascal displays Pascal re- 
served words like begin and end. 
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Indentation This option lets you choose the indentation style that THINK 
Pascal uses to pretty-print your program. 


Parameters This option lets you choose whether parameter lists appear on one 
line or whether they are stacked one on top of the other. 


Auto-Reformat 

This command lets you specify when THINK Pascal pretty-prints your program. This option 
is initially checked, and THINK Pascal reformats your program every time you press the 
Return key or the semicolon (;) key. If you uncheck this option, THINK Pascal will pretty- 
print your program only when you press the Enter key or when you move the insertion point 
to another line. 


The Search Menu 


Search 


Find... The commands in the Search menu let 

Fi ; you find and replace strings in your 
pons Again # source files. THINK Pascal lets you look 
Find in Next File for strings among all the files in your pro- 
Enter Selection ject. 


Replace 
Replace and Find Again 
Replace All 


Show Selection 
Show Error 


Find... 


This command lets you specify the string to search for. If the string is found, THINK Pascal 
highlights it. If it’s not found, you'll hear a beep. 
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At the start of an editing session, only the Find... command is active. The dialog box that ap- 
pears when you choose this command lets you specify the search string as well as the re- 
placement string: 


Search for | myWindow 


@ Separate Words © All Occurrences 
@ Case Is Irrelevant ©Cases Must Match 
OCOMulti-File Search 


The four radio buttons let you specify how the editor looks for your string. 


Separate Words When you click on this radio button, the search matches only 
whole words. 


All Occurrences When you click on this radio button, the search matches even if 
the search string is embedded in a longer string. 


Case is Irrelevant When you click on this radio button, the search treats uppercase 
and lowercase characters as if they were the same. 


Cases Must Match When you click on this radio button, the search will match only if 
the string matches exactly. 


Note: Searching with the Separate Words button on is substantially faster 
than searching with the All Occurrences button on. 


The Multi-File Search check box lets you look for the search string in all the source files in 
your project. See Chapter 6 and the description for the Find in Next File command for more 
information about searching through more than one file. 


In addition to the Find button (“Go ahead with the search”) and the Cancel button (“Pretend I 
never invoked this command)”), there is a Don’t Find button. Clicking on this button sets up 
the search and replacement strings without actually doing the search. The Don’t Find button 
is useful for setting things up for a Replace All... command. 

Find Again 


This command searches for the next occurrence of a previously specified string. 


Find in Next File 
This command lets you search for a string through more than one file. 
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To use this command, you must check the Multi-File Search check box in the Find... dialog. 


THINK Pascal will look for the string specified in the Find... dialog box through each of the 
files in your project. If it finds the strings, THINK Pascal opens an edit window containing the 
file, and selects the search string. At this point, you can go on and make any edits you 
choose. If you want to search further in the current file, you can use the Find Again, 
Replace, and Replace All commands, which work within the current file. When you’re 
ready to go on with the mullti-file search, use the Find in Next File command. 


Multi-file search is useful when you are writing a program, and decide to modify a routine 
that is used in several files. You can open each of the files containing the search string, so 
you can switch back and forth between the various edit windows as necessary. (This feature 
is also helpful when you are tracking down link errors due to undefined or multiply defined 
symbols.) 


Enter Selection 


This command sets the search string to the current selection, You can then use Find Again to 
begin searching, or Find... to set search options. This command clears Multi-File Search if it 
was set. 


Replace 


This command replaces the current selection with a replacement string. If you haven’t pro- 
vided a replacement string, this command will be dimmed. 


Replace and Find Again 

This command replaces the current selection with the replacement string, then finds the next 
instance of the search string, but does not replace it. Use this command to step through a se- 
ries of replacements. After each replacement, you will see the next instance of the search 
string, so you can decide whether you want to replace it. If you want to replace the string, 
use the Replace or Replace and Find Again commands. If not, use the Find Again com- 
mand to find the next occurrence of the string. 


If you haven't provided a replacement string, this command will be dimmed. 


Replace All 


This command replaces every instance of the search string from the current cursor position to 
the end of the file. Use this command when you don’t want to give your approval for every 
replacement. 
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Show Selection 


This command lets you get back to the insertion point or the beginning of the current selec- 


tion if you've scrolled away from it. 


Show Error 


This command lets you see where THINK Pascal has detected an error in your program if 


you've scrolled away from it. 


The Project Menu 


Project 
New Project... 
Open Project... 38P 
Close Project 
Add Window 
Add File... 


Build Library... 
Build Application... 
Remove Objects 
Set Project Type... 
Compile Options... 
View Options... 


New Project... 


The commands in the Project menu work with 
the current project. You can open and create 
projects, set the project type, make sure all the 
files in the project are compiled and loaded. This 
menu also contains the commands you'll use 
when you're ready to build a file containing 
your application, desk accessory, device driver, 
or code resource. 


This command creates a new project document and opens an empty project window. The 
project window will include entries for the default libraries Runtime .1ib and 
Interface.1ib. You can then add files to the project with the Add File... or Add 
Window commands. Only one project can be open at a time. 


Open Project... 


This command opens an existing project. 
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Close Project 


This command closes the current project. If a project still has open files that haven’t been 
saved, THINK Pascal will ask you if you want to save the files before closing the project. 


Note: When you click in the project window’s close box, THINK Pascal just 
hides the project window without closing the project. To close the project, 
use this command or hold down the Command key when you click in the 
project window’s close box. 


When you close a project, THINK Pascal lets you open another project. If you don’t want to 
open another project, just click on the Cancel button. 


Add Window 
This command adds the current THINK Pascal edit window to the project. If the current edit 
window is an Untitled window, THINK Pascal will ask you to save the file first. 


Add File... 
This command lets you add files to the current project. 


You can add four kinds of files to your project: 
e THINK Pascal source files 
e THINK Pascal libraries 
¢ THINK’s LightspeedC libraries 
¢ Macintosh Programmer's Workshop object files (. 0 files) 


Remove 
This command lets you remove the selected source file or library from the project. 


Build Library... 

This command saves the current project as a library that you can add other projects. A dialog 
box prompts you for the name of the library file. By convention, library files end in . Lib, but 
any valid file name is OK. 


To learn how to create libraries, see Chapter 10. 
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Build Application... 

Build Desk Accessory... 

Build Driver... 

Build Code Resource 

This command saves the current project as an application, desk accessory, device driver, or 
code resource. A dialog box lets you name the resulting file: 


© Applications 


Save Application as 


AboutBox 1,0d23 Cancel 


& Smart Link 


If the Smart Link option is checked, THINK Pascal uses only the referenced object code of the 
source and libraries to create the resulting file. It takes a little longer to put the application or 
resource together, but the resulting file will be as small as possible. Uncheck this option if 
you're building frequently for testing. 


When THINK Pascal builds your project with one of these commands, it merges the resource 
from the resource file you specified in the Run Options... dialog box into the resulting file. 


Remove Objects 


This command removes all the object code from a project. All source files will have to be re- 
compiled, and all libraries will have to be reloaded. 


Use the Remove Objects command when you need to make the project document as small 
as possible for archiving or for transmitting to someone else. 


Set Project Type... 

This command lets you set the project type. The default project type is Application, but you 
can change it to Desk Accessory, Driver, or Code Resource. All project types let you specify 
the file type and creator of the file created by one of the Build... commands. To learn the 
details of each kind of project type, see Chapter 12. 
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Note: It’s best to set the project type before you compile any of your source 
files. THINK Pascal will need to recompile all your source files if you change 
the project type once there is compiled code in the project. 


APPLICATION File Information 


The Application presets the type to APPL 2. is [FPL] creator: (EEEEM) 2 aundie ait 
and lets you fill in the creator. 


~ Resauree Information 


Bundle Bit If this option is on, THINK Pascal sets the bundle bit in the result- 
ing file when you use one of the Build... commands. The bundle 
bit lets the Finder know that the file contains a BNDL resource, 
which is used to display the application’s icons. 


DESK ACCESSORY File Information ——— 
DRIVER “a [ sm: [ort] creator: Counate ait 
The Desk Accessory and Device Driver ere scanned inigimalioa 

dialogs are similar. For desk accessories, Name: 

THINK Pascal presets the file type and Type: [onUA_] w; [2] 
creator so the resulting file will be a Attributes: 5 [00] Ccustom teoner 


FonVDA Mover file. There are other dif- 
ferences between desk accessories and 
device drivers. See Chapter 12 for details. 


Driver Information --—--—- 
rege [eno] ove [& —] ( 
Mosk: faj[0168 ] C)Multi-segment 


[— File information 


Type: [2777] Creator: [2777 C1Bunate Bit 


;— Resource Information 
Neme: 


Type: 


Driver Information 


Flogs: G[4F00 | Detey: [0 | | 
Mask: fj [0000 ] C)Multi-segment Cancel 


Name This field is the name of your desk accessory or device driver. By 
convention, desk accessory names begin with a null byte and de- 
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Type 


Attributes 


Flags 


Delay 


Mask 


Multi-Segment 
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vice driver names begin with a period. THINK Pascal automatically 
inserts the null for you in desk accessories and adds the period to 
device driver names if you’ve left it out. 


Desk accessories and device drivers are resources of type DRVR. 
You can change the type if you have some reason for doing so. 


This field is the number of the DRVR resource. Desk accessories 
default to 12. The Font/DA Mover will renumber it (and its owned 
resources) for you if there is an ID conflict with an installed desk 
accessory, so you shouldn't have to change the number. 


This pop-up menu let you set the attributes for the DRVR resource, 
To learn about resource attributes see Inside Macintosh I, Chapter 
5, “The Resource Manager.” 


This pop-up menu lets you set the drvrFlags field of the driver's 
header, These flags let the operating system know what driver 
calls your driver responds to. The default for desk accessories is 
$0400. For device drivers the default is $4F00. For more informa- 
tion about driver headers, see Inside Macintosh II, Chapter 6, “The 
Device Manager.” 


This field lets you set the drvrDelay flag of the driver's header. 
The value in this field lets the operating system know how often it 
needs to call your driver for some periodic action. For this field to 
make sense, you must have the dNeedTime bit set in the drvr- 
Flags field. 


This pop-up menu lets you set the drvrEMask field of the driver's 
header. The mask lets the system know which events your desk 
accessory responds to. (This field isn’t used in device drivers.) 


When this option is checked, your desk accessory can have up to 
31 segments. If your desk accessory uses Object Pascal, this option 
must be on. 
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CODE RESOURCE File Information 
The Code Resource dialog lets you specify Type: Creator: CBundie ait 


the type, name, id, and attributes of your 
code resource. 


Resource Information 


Type: 


Attributes: [00] (custom Header 
- Briver Infarmation ————— 
| a 
=F OOMuttt-seqment 


Name This field lets you name your code resource. For most code re- 
sources, the name is optional. 


Type This field lets you specify the type of the code resource. 
ID This field lets you specify the ID of the code resource. 
Attributes This pop-up menu lets you specify the attributes of your code re- 


source. To learn about resource attributes see Inside Macintosh I, 
Chapter 5, “The Resource Manager.” 


Custom Header When this option is on, THINK Pascal does not generate the stan- 
dard resource header. Instead, the object code for file that contains 
main is guaranteed to appear first in the resource. See Chapter 12 
for details. 
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Compile Options... 


This command lets you define compile-time variables for the project, and it lets you specify 
some code generation options. When you choose this command, you'll see this dialog box: 


Compile Options 


Compile-Time Variables Code Generation 


THINK_PASCAL=TRUE; CO) Mcesest 
Elems881=TRUE; CO Mceso20 


SET OF Integer 
@ 0..255 
© -32768 .. 32767 


You can define any compile-time variables in the large edit box just as if you had used the 
{ $SETC} compiler directive. 


The two check boxes tell THINK Pascal to generate code for the MC68020 and for the 
MC68881 floating point processor. For more information about the specific kind of code 
THINK Pascal generates when you check these options, see Chapter 15. 


Note: THINK Pascal doesn’t check to see whether the machine you're writ- 
ing your program on or whether the machine your application runs on has 
an MC68881 coprocessor. Use the Toolbox routine SysEnvi rons to check 
the features of the Macintosh you’re program is running on. If you want to 
check for the machine's capabilities, you'll need to turn off automatic initial- 
izauions. 


Set of integer option 


The two radio buttons control the way THINK Pascal generates code for sets of integer. 
THINK Pascal lets you specify whether sets of integer include all integers (-32768 . . 32767) 
or just the range 0. .255. Most of the time, you’ll use the smaller set range. The larger set 
range takes up considerably more space in your program and takes much longer to access 
than the smaller range. Sets of the range 0. .255 can take up at most 32 bytes. Sets of the 
range -32768..32767 can take up to 8192 bytes. 
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View Options... 


This command lets you customize what appears in the project window. When you choose 
this command, you'll see this dialog box: 


Project View Settings 


Options File (by build order) Size 
[N] v [R] MemHacks 32767 
[NIMIIR) Extremely w-i-d-e... 10 


Eifilename Clunitname [Geneva] [3] 


& options Clvolume name 
code size [date file saved | 


File Information 


Options - Boxed indicates enabled 
D - Debug. Allows stepping, stopping, stack checking, Observing. 
N- Names. Insert Macsbug names into the code. 
U - Integer arithmetic overflow checking. 
R - Range checking. 


The two pop-up menus let you choose the font THINK Pascal uses to display the file names 
in the project window. The check boxes let you choose the information that appears for each 
file. The box at the top of the dialog box shows you what the project window would look 
like with the current settings. 


Option Meaning 

filename Displays the name of the file. 

options Displays the compiler options. 

code size Displays the size of the compiled code. 

unit name Displays the unit name if the file has been compiled. 
volume name Displays the volume or folder the file is in. 

date file saved Displays the last date and time you saved the file. 


The order that you click the check boxes determines the order of the display. 
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The Run Menu 


Check 38K 
Build 3B 
Check Link 


The commands and options in the Run menu let 
you compile your program and control the exe- 
cution of your project. 


Auto Save 
Confirm Saves 
Don't Save 


Bun Options... 


Check 
This command checks the Pascal syntax of the current edit window or of the Instant window. 


Build 


This command compiles all the files that have changed or that use a unit whose interface 
section has changed, 


The execution commands — Go, Go-Go, Step, and Trace — do an implicit Build before 
executing the program. 


Check Link 


This command links all the files in the project. If THINK Pascal finds an undefined symbol or 
a symbol defined more than once, it reports an error. 


The execution commands — Go, Go-Go, Step, and Trace — do an implicit Check Link be- 
fore executing the program. If there are files that need to be recompiled, THINK Pascal will 
ask you if you want to recompile them. 


THINK Pascal Menus 1 


Reset 


This command resets a paused program. The next execution command — Go, Go-Go, Step, 
and Trace — starts the program from the beginning. 


Go 
This command runs the program. If necessary, it builds the project first. 


If the program encounters a Stop during execution, it will stop right before the Stop sign. 


Go-Go 

This command is just like the Go command except that instead of stopping at Stops signs it 
just pauses long enough to update the values in the Observe and LightsBug window and then 
continues execution. 


Step 


This command executes the next statement in your program. If the statement is in an open 
edit window, the execution finger points to the statement about to be executed. 


If you hold down the Shift key when you choose the Step command, THINK Pascal will 
break into the low-level debugger (TMON or Macsbug) at an RTS instruction just before the 
actual code for the statement. 


Trace 


You can think of this command as an automatic version of the Step command. It executes 
your program statement by statement, pausing long enough between statements to update 
the Observe and LightsBug windows. 


Auto-Save 

Confirm Saves 

Don’t Save 

These three options determine what THINK Pascal does with files that you’ve changed but 
haven't saved when you choose one of the execution commands in the Run menu. 


The three options are mutually exclusive. You can choose only one. 


Auto-Save When this options is checked, THINK Pascal automatically saves 
your files before running your project. 


If you hold down the Shift key and then choose Auto-Save, ‘THINK 
Pascal saves all your unsaved files without changing the current 
option. 


Confirm Saves When this option is checked, THINK Pascal asks if you want to 
save your unsaved files before running your project. 
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Don’t Save 


Run Options... 


If you hold down the Shift key and then choose Confirm Saves, 
THINK Pascal will ask you if you want to save each of your un- 
saved files. 


When this options is checked, THINK Pascal doesn’t do anything 
with your unsaved files before running your project. 


This command lets you set up certain run-time environment settings. When you choose this 
command you'll see this dialog box: 


Resources 


Memory 


Run-time Environment Settings 


for resources used by the project. 


Text Window saves [5000 |characters 


(Echo to the printer 


Hello world. x = 811.79. 
mm 


Stack size:|[[G| kilobytes | 
Zone size:|128 |kilobytes 


Resources 


When you check this box, THINK Pascal lets you choose the re- 
source file your program will use. To learn more about using re- 
source files with your THINK Pascal projects, see Chapter 8 and 
Chapter 12. 


Note: THE RESOURCE FILE MUST BE IN THE SAME FOLDER AS THE 


PROJECT. 


Text Window 
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This part of the dialog lets you configure the THINK Pascal Text 
window. THINK Pascal uses the Text window for all standard out- 
put, for instance write, writeln, read, etc.. 
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You can specify how many characters THINK Pascal will save in 
the Text window. The default is 5000 characters. If you write more 
than that to the text window, the earlier text disappears. 


The Echo to printer and Echo to a file check boxes let you send 
the standard output to the printer or to a file as well as to the Text 
window. 


The pop-up menus let you choose the font and size of text in the 
Text window. 


Memory These options let you choose how much memory THINK Pascal 
allocates for your project’s stack and heap zone. If your program is 
running out of memory, try making the zone size bigger. If your 
program allocates a lot of local variables, or if it uses very deep re- 
cursion, you might want to make the stack size bigger. In most 
cases, 16K is more than enough. 


The Debug Menu 


The Debug menu commands and options let 


Show Finger 
you control THINK Pascal’s debugging features. 


Pull Stops 


Auto-Show Finger 
Stops In 
Step Into Calls 


Show Finger 


This command makes the window that contains the execution finger the active window. If 
necessary, it scrolls the window so you can see the execution finger. If the window that 
would contain the execution finger is not open, the project window becomes the active win- 
dow, and the execution finger points at the file name. 


Pull Stops 
This command removes all Stop Signs from the current edit window. 
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Auto-Show Finger 


You can think of this command as an automatic version of Show Finger. When this option is 
checked, and THINK Pascal is executing a Step, Go-Go, or Trace command, the window 
that contains the execution finger becomes the active window. If the file that would contain 
the execution finger isn’t opened, the execution finger points to the file name in the project 
window. 


Since this command changes the active window, it’s a good idea to turn this option off when 
you're debugging the code that handles update events in your application. 


Stops In 


This option lets you add Stops to your Pascal code. To add a Stop to your program, move the 
cursor to the left column of your program. The cursor will change to a Stop sign. When you 
click the mouse, a Stop sign will appear to the left of the line of code. 


To remove a Stop Sign, just click on it. 


When you choose the Go or Go-Go command, THINK Pascal will stop execution right before 
the Stop sign. 


Step Into Calls 


When this option is on, the Go-Go, Step, and Trace commands will step into the bodies of 
procedures and functions. When this option is off, procedures and functions are treated as 
single statements. 


Break at A-Traps 

When this option is on, THINK Pascal will stop execution before calling a Macintosh Toolbox 
routine. Use this option to make sure that you’re passing the proper values to Toolbox rou- 
lines, 

Monitor 

This command drops you into the low-level debugger (Macsbug or TMON) if it’s installed. 
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The Windows Menu 


Windows 
No project JEP 
LightsBug 
Instant 
Observe 


The commands in the Windows menu help you 
work with the THINK Pascal windows. 


He giabia i 
Hvgvabie 3&2 
Hvalahie eS 
Hpalabie HEE 
Hpahahie 3S 
Hpalahbie 3G 
Hpaahie Beare 
Hvaglania 


Project name 
This command makes the project window the active window. 


LightsBug 


This command opens a LightsBug debugging window. You can open up to four LightsBug 
windows. To open another LightsBug window, hold down the Shift key as you choose this 
command. 


Choosing the LightsBug command (or its Command key equivalent) when LightsBug win- 
dows are open cycles through all the open LightsBug windows. 


Instant 


This command opens the Instant window, which is used for executing statements when your 
program is paused. 
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Observe 

This command opens the Observe window, which displays the values of expressions during 
program execution. 

Text 


This command opens the Text window which THINK Pascal uses for standard output like 
write and writeln. 


Drawing 


This command opens the Drawing window which THINK Pascal uses as the default drawing 
port for your program. 


Clipboard 
This command opens the Clipboard window. 


File Windows 

Use these commands to activate one of the currently open editing windows. A diamond ap- 
pears next to files which have been changed but haven’t been saved. If you hid a window by 
clicking in its close box, choosing its name in this menu makes it visible. 
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Introduction 


This chapter describes the Pascal language implemented by THINK’s Lightspeed Pascal. 
THINK Pascal is intended to be compatible with Macintosh Pascal, Apple’s Macintosh 
Programmer’s Workshop Pascal, and American National Standard Pascal. Naturally, it’s 
impossible to be completely compatible with all three implementations. Appendixes A and B 
detail the differences between THINK Pascal and other implementations of Pascal. 


Related Documents 


Pascal User Manual and Report, Third Edition (ISO Pascal Standard) by Jensen and Wirth, 
revised by Mickel and Miner, Springer-Verlag, New York, 1985. 


American National Standard Pascal Computer Programming Language, ANSI/ 
TEEE770X3.97-1983, IEEE/Wiley-Interscience, 1983. 


Object Pascal Reportby Larry Tesler. Apple Technical Report No. 1. Apple Computer 1985. 
Inside Macintosh I-V, Addison Wesley, 1985-1988. 
Apple Numerics Manual, Second Edition (Addison-Wesley) 


Definitions 
This chapter uses these definitions for the terms error, undefined, and unspecified: 


Error Any misuse of the Pascal language described in this chapter. Most 
of these errors are detected at compile time or at run time, Other 
errors are not detected; these are listed in Appendix A. The 
behavior of a program that contains undetected errors is 
unspecified. 


Undefined A value of a variable or of a function that is not meaningful. It is an 
error to use an undefined value. 


Unspecified When a situation arises in the execution of a program where sev- 
eral courses of action are possible, the specific course chosen is 
said to be unspecified. This means that the program should not 
depend on any specific course being chosen, as the result may be 
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unpredictable. This leaves the implementation free to choose the 
course that is most convenient at the time. 


Notation and syntax diagrams 


All numbers in this manual are in decimal, except where hexadecimal notation is specifically 
indicated. 


In this section, Pascal text is in typewriter text, and Pascal reserved words are in bold 
typewriter text. For example: 


sqr(n div 16) 


Sometimes the same word appears both in plain text and in typewriter text. For example, 
“The declaration of a Pascal procedure begins with the word procedure.” 


Technical terms appear in bold face when they’re introduced. 


Pascal syntax is specified with diagrams. For example, this diagram gives the syntax for an 
identifier: 


identifier 


d 


igit 


underscore 


Start at the left and follow the arrows through the diagram. There are several paths you can 
take. Every path begins at the left and ends at the arrow-head on the right, and represents a 
valid way to construct an identifier. The boxes represent the elements that can be used to 
construct an identifier. The diagram represents the following rules: 


¢ An identifier must begin with a letter, since the first arrow goes directly to a box named 
“letter”. 


¢ An identifier might consist of nothing but a single letter, since there is a path from this 
box to the arrow-head on the right, without going through any more boxes. 


¢ The initial letter may be followed by another letter, a digit, or an underscore, since there 
are branches from the initial letter box to these boxes. 
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¢ The initial letter may be followed by any number of letters, digits, or underscores, since 
there is a path that leads from these boxes back to them again. 


A word contained in a rectangular box may be a name for an atomic element like “letter” or 
“digit,” or it may be a name for some other syntactic construction that is specified by another 
diagram. The name in the rectangular box is to be replaced by an actual instance of the atom 
or construction that it represents, e.g. 3 for “digit” or counter for “variable-reference”. 


Pascal symbols, such as reserved words, operators, and punctuation, are in bold face and 
are enclosed in circles or ovals, as in the following diagram for the construction of a com- 
pound-statement: 


compound-statement 


Text in a circle or oval represents itself, and is written as shown (except that case of letters is 
not significant). In the diagram above, the semicolon and the words begin and end are 
symbols. The word “statement” refers to a construction that has its own syntax diagram. 


So this diagram means that a compound-statement consists of the reserved word begin, 
followed by any number of statements separated by semicolons, followed by the reserved 
word end. 


1.0 Tokens and Constants 


Tokens are the smallest meaningful units of text in a Pascal program. Structurally, they 
correspond to the words and punctuation of an English sentence. The tokens of Pascal are 
classified into special symbols, identifiers, numbers, labels, and character-strings. 


The text of a Pascal program consists of tokens and separators, where a separator is cither a 
blank or a comment. Two adjacent tokens must be separated by one or more separators if 
each token is an identifier, number, or word-symbol. 


Separators cannot be embedded within tokens except in character-strings. 


1.1 Character set and special symbols 
THINK Pascal uses the Macintosh character set. Letters, digits, hex-digits, and blanks are 
subsets of the character set: 


* Letters are the characters A through Z and a through z. 
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* Digits are the Arabic numerals 0 through 9; the hex-digits are the Arabic numerals 0 
through 9, the letters A through F, and the letters a through f. 


¢ The blanks are the space character and the end-of-line character (CR). 


Special-symbols and word-symbols (also called reserved words) are tokens that have 
one or more fixed meanings. The following single characters are special-symbols: 


The following character-pairs are special-symbols: 


<> <= >= = af te Ay A> yl 


Note: The special symbol (. is an alternate representation for the special 
symbol [. Both actually denote the same special symbol. If you type (. in 
a THINK Pascal program, it will always be displayed as [. The same is true 
for.) and}. 


The following are the word-symbols: 


and function object to 
array goto of type 
begin if or unit 
case implementation otherwise univ 
const in packed until 
div inherited procedure uses 
do inline program var 
downto interface record while 
else label repeat with 
end mod set 

file nil string 

for not then 


Upper and lower case letters are equivalent in word-symbols. 
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1.2 Identifiers 

Identifiers serve to denote constants, types, variables, procedures, functions, programs, and 
fields in records. Identifiers can be up to 255 characters long. All characters are significant. 
Upper and lower case letters are equivalent in identifiers. No identifier can have the same 
spelling as a word-symbol. 


identifier 


Examples of identifiers: 


X Rome gcd SUM get_byte 


1.3 Directives 


Directives are identifiers that have special meanings in specific contexts. They can be used as 
identifiers in all other contexts. For example, the word forward is interpreted as a directive 
if it occurs immediately after a procedure-heading or function-heading, but in any other 
position it is interpreted as an identifier. 


THINK Pascal recognizes these three directives: 


external 
forward 
override 


Note: Don’t confuse these directives with compiler directives. 


1.4 Numbers 


The usual decimal notation is used to represent numbers that are constants of the data types 
integer, longint, real, double, extended, and computational (see § 3.1). A 
hexadecimal integer constant uses the $ character as a prefix (1-4 hex-digits for integer, 5- 
8 hex-digits for Longint). 


digit-sequence [ast] 
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hex-digit-sequence 
ei hex-digit — 
unsigned-integer 
bar digit-sequence a 
(3°) hex-digit-sequence 


sign 


unsigned-reaj 


digit-sequence 


scale-factor 


scale-factor 


signed-number 


unsigned-number 


The letter E or e preceding the scale in an unsigned-real means “times ten to the power of.” 
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Examples of numbers: 


1 +4100 0,1 SE+3) 87.35e+8 ‘SA05D 


Note that 5E-3 means 5x10°3, and 87.35e+8 means 87.35x108. 


1.5 Labels 


A label is a digit-sequence whose value is in the range 0 through 9999. Leading zeros in a 
label are insignificant. The labels 1 and 0001 are equivalent. 


1.6 Character-Strings 

A character-string is a sequence of zero or more printing characters on the same line ina 
program and enclosed by single quotes. The maximum number of characters that can be in a 
character-string is 255. A character-string with nothing between the apostrophes is a 
null-string value (sce §3.3). Two adjacent apostrophes in a character-string denotes a single 
apostrophe character. 


character-string 


A character-string represents a value of a string-type. As a string-type, a character-string is 
compatible not only with other string-types, but also char-types (see §3.1.1.1) and packed- 
string-types (§3.2.1). 


All string-type values have a length attribute. In the case of a character-string, the length is 
fixed; it is equal to the number of characters in the string as enclosed within apostrophes. 
Two adjacent apostrophes within a character-string count as a single apostrophe and thus 
count as a single character in the string’s length. 


Examples of character-strings: 


‘Pascal' ‘THIS IS A STRING' 'Don''t worry!' 


tat Vat vont uw 
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1.7 Constant-Declarations 


A constant-declaration declares an identifier to denote a constant within the block that 
contains the declaration. A constant-identifier may not be included in its own declaration. 


constant-declaration 


constant 


A constant-identifier following a sign must denote a value of type character-string, integer, 
longint, boolean, char, real, double, computational or extended (see §3.1). 


A constant expression must evaluate to integer, longint, boolean or char. You can 
use the following operators and standard functions in a constant expression: 


¥ abs 
# chr 
= ord 
div sizeof 
mod sqr 


1.8 Comments 
The constructs: 


{ any text not containing right-brace } 


(* any text not containing star-right-paren *) 


are called comments. 
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You can use a comment anywhere you can use a blank. THINK Pascal moves any comments 
embedded in a line of code to the end of the line. Comments that appear alone on a line are 
left alone. 


You can’t nest comments within other comments. A } or a *) always terminates a comment. 


1.9 Compiler Options 

A compiler option is a comment that contains the $ character immediately following the 
initial comment delimiter; for example, {$ or (*$. The $ character is followed immediately 
by the mnemonic of the compiler option. (see Chapter 15 for available options). A compiler 
option is always on a line by itself. 


2.0 Blocks, Scopes, and Activations 


2.1 Definition of a Block 


A block consists of a declaration-part and a statement-part. Every block is part of a pro- 
cedure-declaration, a function-declaration, or a program. All identifiers and labels that are 
declared in the declaration-part of a block are local to that block. 


block 
declaration-part statement-part 


declaration-part 


a label-declaration-part ae 


- : constant-declaration-part —: 
type-declaration-part 
variable-declaration-part 


procedure-and-function-declaration-part 


A label-declaration-part declares labels (see §1.5) that mark statements in the corre- 
sponding statement-part. Each label must mark exactly one statement in the statement-part. 


THINK’s Lightspeed Pascal 


label-declaration-part 


label 
digit-sequence 


A constant-declaration-part contains constant-declarations (see §1.7) local to the block. 


constant-declaration-part 


=" constant-declaration Ee 


A type-declaration-part contains type-declarations (see §3) local to the block. 


type-declaration-part 


type fai type-declaration % 


A variable-declaration-part contains variable-declarations (see §4) local to the block. 


variable-declaration-part 


var ee variable-declaration Ss 


A procedure-and-function-declaration-part contains procedure-, function-, and method- 
declarations (see §7) local to the block. 


procedure-and-function-declaration-part 
i= procedure-declaration if 
function-declaration 


aa 


method-declaration 


The statement-part specifies the statements or algorithmic actions (see §6) to be executed 
upon an activation (see §2.3) of the block. 
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Note: A method declaration can only be declared in the declaration-part of a 
program or in the implementation part of a unit, not in the declaration-part 
of a procedure or function. 


statement-part 
compound-statement 


2.2 Rules of Scope 


This section describes the rules that THINK Pascal uses to determine what identifiers are visi- 
ble to a particular block. 


2.2.1 Scope of a Declaration 

The appearance of an identifier or label in a declaration declares the identifier or label, All 
other applied occurrences of the identifier or label must be within the scope of this declara- 
tion. 


The scope of a declaration is the block that contains the declaration, and all blocks enclosed 
by that block except as explained in §2.2.2 and §2.2.4 below. (See also §8.3 for scope rules for 
Units.) 


2.2.2 Redeclaration in an Enclosed Block 

Suppose that outer is a block, and that inner is another block declared within outer. If 
an identifier declared in block outer has the same spelling as an identifier declared in block 
inner, then block inner and all blocks enclosed by inner are excluded from the scope of 
the declaration in block outer. 


2.2.3 Position of Declaration within Its Block 

The declaration of an identifier or label must precede all applied occurrences of that identifier 
or label in the program text. In other words, identifiers and labels cannot be used until they 
are declared. 


There are two exceptions to this rule. In a type-declaration-part, the base-type of a pointer- 
type (see §3.4) can be an identifier that has not yet been declared. In this case, the identifier 
must be declared somewhere in the same type-declaration-part as the pointer-type. ‘The base- 
type of an object-type (§3.2.5) can also be an identifier that has not been declared, and the 
identifier must be declared somewhere in the same type-declaration-part as the object type. 


2.2.4 Redeclaration within a Block 
An identifier or label cannot be declared more than once within a block, unless it is declared 
within a contained block, or it is in a record’s field-list. 


A field-identifier (see §§3.2.2 and 4.3.2) is declared within a record-type. It is meaningful only 


in combination with a reference to a variable of that record-type. Therefore, a field-identifier 
can be declared within the same block as another identifier with the same spelling, as long as 
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it has not been declared previously in the same field-list. An identifier that has been declared 
can be used again as a field-identifier in the same block. 


2.2.5 Identifiers of Standard Objects 

THINK Pascal provides a set of standard (predeclared) constants, types, procedures, and 
functions that behave as if they were declared in a block that contains the entire program. In 
addition, there are two standard file variables, input and output, that (if used) are 
“declared” in the program block itself (see §9.4). 


2.2.6 Scope of Interface Identifiers 

Each interface-part or program with a uses-clause (see §8.4) is supplied with the identifiers 
associated with the unit given in the uses-clause. This means that these identifiers behave as 
though they were declared directly in each interface-part or program with the uses-clause. 


2.2.7 Scope of fields 

In the implementation of a method of an object-type (§3.2.5) all of the identifiers and 
components of the type and its ancestors are meaningful. The behavior is as if the statement- 
list of the block were wrapped in with self do begin .., end. 


2.3 Activations 


The execution of a block is referred to as an activation of the block. At any given time, a 
block normally has either no activations (if it is not currently being executed) or one activa- 
tion Cif it is begin executed). It is, however, possible for a block to have multiple activations if 
it is recursive or if it is mutually recursive with one or more other procedures or functions. 
A typical example of a recursive function is: 


function factorial (n: integer): integer; 


begin 
if n<=1 then 
factorial :=1 
else 
factorial := n * factorial (n-1) 
end; 


Thus, the execution of factorial (5) would lead to 5 activations of factorial as fol- 
lows: 


factorial (5) = factorial (4) 
4 * factorial (3) 
*3 * factorial (2) 
* 2 * factorial (1) 
* za * af 


+ * *  % 


"1 
aonwnn uo 


4 
A # NS 
a + 3 
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Factorial calls itself repeatedly, creating new activations, until the parameter n is less than 
or equal to 1. The last activation then unwinds itself by passing back a result and terminating 
the activation. The next to last activation then performs the multiplication with the result, 
passes back its result, and terminates its activation, and so on, 


Every activation has, in effect, its own copy of every parameter and variable declared local to 
the block being activated. Thus, each activation of factorial has its own copy of its pa- 
rameter, which is named n in all activations. Because each activation has its own copy of all 
locally declared entities, it does not disturb the local entities of any previous activation. §7.3.3 
gives a very detailed example of this. 


The activation of the program-block also creates the variables local to each used unit’s inter- 
face-part and implementation-part (see §8.3). This means that there is only one copy of each 
unit’s local variables and that they exist as long as the program is executing. 


Note: The value of a variable declared within a particular block is undefined 
for each new activation of the block. Likewise, the value of every 
component of a structured-type variable (see §3.2) is initially undefined for 
each new activation. The value of a structured-type variable remains unde- 
fined until it has no components whose values are undefined. 


3.0 Types 


A type is used in declaring variables and in declaring other types. The type of a variable de- 
termines the set of values the variable can assume and the operations that can be performed 
upon it. A type-declaration associates an identifier with a type. 


type-declaration 


Oe LO 
simple-type 
i structured-type t 
es string-type Ee 


pointer-type 


type 
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The occurrence of an identifier on the left-hand side of a type-declaration declares it as a 
type-identifier for the block in which the type-declaration occurs. A type-identifier may not 
be included in its own declaration, except for pointer-types (see §2.2.3 and §3.4). 


To help clarify the syntax description with some semantic hints, the following terms dis- 
tinguish identifiers according to the type they denote. Syntactically, all of them simply mean 
an identifier: 


simple-type-identifier 

structured-type-identifier 

pointer-type-identifier 

ordinal-type-identifier 

integer-type-identifier 

real-type-identifier 

string-type-identifier 
In other words, a simple-type-identifier is any identifier that is declared to denote a simple- 
type, a structured-type-identifier is any identifier that is declared to denote a structured-type, 


and so forth. A simple-type-identifier can be the identifier of a standard simple-type such as 
integer, boolean, etc. 


3.1 Simple-Types 
All the simple-ty pes define ordered sets of values. 


simple-type : 
he ordinal-type ae 
real- 


type 


real-type 
real-type-identifier 


ordinal-type 


subrange-type 


enumerated-type 
ordinal-type-identifier 


An integer-type-identifier is one of the standard identifiers integer or longint. Constant inte- 
ger-lype values can be denoted as described in §§1.4 and 1.7. 
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A real-type-identifier is one of the standard identifiers real, double, extended, or com- 
putational. Constant real-type values can be denoted as described in §§1.4 and 1.7. 


3.1.1 Ordinal-Types 
Ordinal-types are a subset of the simple-types that have the following special charac- 
teristics: 


e The possible values of an ordinal-type are an ordered set and every value has an ordi- 
nality, which is an integral value. Except for integer-types, the first value of every ordi- 
nal-type has ordinality 0, the next has ordinality 1, etc. For integer-types, the ordinality of 
a value is the value itself. Every value of an ordinal-type except the first has a predeces- 
sor based on the ordering of the type, and every value of an ordinal-type except the last 
has a successor based on the ordering of the type. 


e The standard function ord (see §10.4.1) can be applied to any value of an ordinal-type, 
and it returns the ordinality of the value. 


¢ The standard function pred (see §10.4.4) can be applied to any value of an ordinal-type, 
and it returns the predecessor of the value. 


¢ The standard function succ (see §10.4.3) can be applied to any value of an ordinal-type, 
and it returns the successor of the value. 


The application of pred to the first value of an ordinal-type is an error. Likewise, the 
application of succ to the last value of an ordinal-type is an error. 


All simple-types except the real-types are ordinal-types. 


There are four standard ordinal-types denoted by the standard identifiers: 


integer 
longint 
char 

boolean 


Note that in addition to the standard ordinal-types, the enumerated-types and subrange-types 
are ordinal-types. 


3.1.1.1 Standard Ordinal-Types 

Integer The integer-type integer has a set of values thal are a subset of 
the whole numbers. The standard integer constant maxint is 
defined to be 215-1, i.e. 32,767. A variable of type integer can 
have any value in the range -maxint-1..maxint. Values of 
type integer are 16-bit, signed, 2s-complement numbers. 
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Longint The integer-type Longint is a type that has a set of values that 
are also a subset of the whole numbers, a somewhat larger subset 
than those of integer. The standard longint constant 
maxlongint is defined to be 231-1, i.e. 2,147,483,647. A variable 
of type longint can have any value in the range 
-maxlongint-1..maxlongint. Values of type longint are 
32-bit, signed, 2s-complement numbers. 


There are several arithmetic operators that may be used to perform arithmetic with inte- 
ger-type values. All arithmetic with just integer-type integer operands yields results of type 
integer. When one or both operands are of integer-type longint, the result is always of 
type longint. A longint value may always be used where an integer value is required 
provided that the value falls within the range -maxint-1..maxint. 


Boolean The ordinal-type boolean is an enumerated-type (see §3.1.1.2) 
defined as: 
type boolean = (false, true); 


As a consequence of boolean being an enumerated-type, the following relationships hold: 


false < true 
ord(false) = 0 
ord (true) Si 
succ(false) = true 
pred(true) = false 
Char The ordinal-type char has a set of values that are characters. The 


ordering of the values is defined by the ordering of the Macintosh 
character set. The function-call ord(c), where c isa char value, 
returns the ordinality of c (see §10.4.1). 


A character-string of length 1 may be used to denote a constant char value, provided that 
the character is a printable character, Any value of type char may be generated via the stan- 
dard function chr (see §10.4.2). 


The redeclaration of a standard type-identifier does not affect the operand-types, parameter- 
types, or result-types of certain standard operators, procedures, and functions declared to be 
that standard type (see §5.1 and §10). Neither does it affect the type of any literal token (such 
as a number) declared to be of that type (see §1). 


The redeclaration of the standard constant-identifiers maxint or maxlongint has no effect 
on the set of possible values for the integer-types. 
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There are several contexts in which an expression is required to be of the standard type 
boolean (see §6). A redeclaration of the standard type-identifier boolean does not alter 
this requirement. 


However, the redeclaration of the standard enumerated-constant identifiers false and true 
will affect the value of these identifiers. 


3.1.1.2 Enumerated-Types 

An enumerated-type has an ordered set of values defined by listing the identifiers that 
denote these values. The ordering of these values is determined by the sequence in which 
the identifiers are listed. 


enumerated-type 
(() identifier-list 0) 


identifier list 
qs 


The occurrence of an identifier within the identifier-list of an enumerated-type declares it as 
an enumerated-constant for the block in which the enumerated- type is declared. The type of 
this constant is the enumerated-type in which it is declared. 


The ordinality of an enumerated-constant is its position in the identifier-list in which it is de- 
clared, where the ordinality of the first enumerated-constant in the list is always 0, The ordi- 
nality of a value of an enumerated-type is the ordinality of the enumerated-constant with the 
same value. 


When the ord function (see §10.4.1) is applied to a value v of an enumerated-type, it returns 
an integer-type value that is the ordinality of v. 


Examples of enumerated-types: 


color = (red, yellow, green, blue) 
suit = (club, diamond, heart, spade) 
maritalStatus = (married, divorced, widowed, singl¢) 


Given these declarations, yellow is an enumerated-constant of type color with ordinality 
1, spade is an enumerated-constant of type suit with ordinality 3, and so forth. 
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3.1.1.3 Subrange-Types 
A subrange-type has a subset of the values of some ordinal-type that lie within a certain 
range. The syntax for a subrange-type is: 


subrange-type 
S 


Both constants in a subrange-type must be of an ordinal-type and both must be of the same 
ordinal-type. For all subrange-types of the form a. .b, a must be less than or equal to b. The 
ordinal-type of a and b is referred to as the host-type of the subrange-type. The values of a 
subrange-type a. .b are those values of its host-type whose ordinalities lie between the 
ordinalities of a and b inclusive. 


Examples of subrange-types: 


1..100 
KLOnFLO 
red. .green 


A variable of subrange-type possesses all the properties of variables of the host-type, with the 
restriction that its value must always be one of the values in the range defined by the sub- 
range-type. 


3.1.2 Real-Types 

The real-types have sets of values that are subsets of the real numbers; in particular those 
subsets of the real numbers that may be represented with a floating-point notation using a 
fixed number of digits. In general, a floating-point notation of a value n is comprised of a set 
of three values m, b, and e such that 


mx be=n 


A real-type uses a floating point notation where b is always 2, and where mand e are integral 
values that lie in a range that depends on the particular real-type. The range of values that m 
and e can have determine the range and precision of the real-type. 


Note: For detailed information about the representation of real-type values, 
see Apple Numerics Manual, Second Edition (Addison-Wesley). 


Doing arithmetic with real-type values can lead to results that cannot even be approximated 
with a floating-point notation. For instance, the division of one by zero is nominally 7, Other 
results make even less sense, such as dividing zero by zero. There are, in fact, special real- 
type values to represent such results. Normally, however, the generation of such a result by a 
program is an error and results in the premature termination of the execution of the program. 
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There are four standard real-types: real, double, extended, and computational. No 
other real-types can be defined. 


The approximate range of positive values representable with the real-types real, double, 
and extended as well as their precision are: 


real-type range decimal digits 
real 1.5x10-45 to 3.4x1038 7-8 

double 5.0x10°324 to 1.7x10308 15-16 
extended 1.9x10-4951 to 1,1x104932 19-20 


Any negative value whose absolute value lies within these ranges is representable with these 
real-types. 


All real-type operands are converted to extended before any arithmetic is performed on 
them, and the results of such arithmetic are always of type extended. An extended value 
may be used anywhere a real or double value is required provided that the value falls 
within the range of values for real or double, respectively. 


The real-type computational is a special real-type where e is always zero, i.e. only in- 
tegral values may be represented with computational. Values of type computational 
must lie in the (exact) range -263+1 to 263-1, which is approximately -9.2x1018 to 9.2x1018, 


All computational operands are converted to extended before any arithmetic is per- 
formed on them, and the results of such arithmetic are always of type extended. An ex- 
tended value may be used anywhere a computational value is required provided that 
the value, when rounded to an integral value, falls within the range of values for compu- 
tational. 


The type computational is intended for those applications where precise, fixed-point 
decimal values are required. No explicit decimal point is ever assumed for a computa- 
tional value, but one can be implicitly assumed by the application. For instance, one can 
define 


type cents = computational; 


and perform calculations on values of type cents that may also be interpreted as cal- 
culations on dollar values with an implied decimal point to the left of the second to last deci- 
mal digit. A special form of the standard procedures write and writeln (see §9.4.3.5) may 
be used to output a computational value with a decimal point inserted between any two 
decimal digits in the value. 
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Note: The SANE data types single and comp are equivalent to the Pascal 
real-types real and computational respectively. All of these names are 
accepted by THINK Pascal. 


3.2 Structured Types 


A structured-type is characterized by the kind of structuring it embodies and by the types of 
the componcnis subject to such structuring. The type of a component may itself be struc- 
tured, in which case the resulting structured-type exhibits more than one level of structuring. 
There is no inherent limit on the number of levels to which types can be structured other 
than the amount of memory available. 


structured-type 


file-type 


object-type 
structured-type-identifier 


The use of the word packed in the declaration of a structured-type indicates that storage 
organization of all values of that type should be compressed to economize storage, even if 
this causes the access of a component of a variable of this type to be less efficient. 


3.2.1 Array-Types 


An array-type is a linear array (or vector) of components that are all of one type, called the 
component-type of the array. 


array-type 


index-type 
index-type 
ordinal-type 
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The type that follows the word of is the component-type of the array. The number of ele- 
ments is determined by the index-type of the array, which must be an ordinal-type. 
If the component-type of an array-type is also an array-type, the result can be regarded as a 
single multi-dimensional array. An equivalent shorthand notation may be used to declare 


multi-dimensional arrays that entails declaring a single array with multiple index-types. For 
example, the type 


array[boolean] of array[1..10] of array[size] of real 


is equivalent to the type 


array[ boolean, 1..10, size ] of real 
where “equivalent” means that they will be interpreted in the same way. 


Examples of array-types: 


array[1..100] of real 
packed array[color] of boolean 


A component of an array can be accessed by referencing the array and supplying one or 
more indices (see §4.3.1). 


An array-type of the form 


packed array[1..n] of char 


is referred to as a packed-string-type with n components (in American National Standard 
Pascal these are called string-types; they are called packed-string-types here to avoid con- 
fusion with THINK Pascal’s string-types (see §3.3). A packed-string-type has certain properties 
not shared by other array-types or structured-types (see §§3.5 and 5.1.5). 
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3.2.2 Record-Types 


A record-type consists of a fixed number of components called fields, each of which may 


be a different type. For each component, the record-type specifies the type of the field and an 
identifier that denotes it. 


record-type 


field-list 


Cia 1407+ Os 


fixed-part 


field-declaration 


field-declaration 
identifier-list G) 


The fixed-part of a record-type specifies a field-list that is always accessible in a variable of 


the record-type, giving an identifier and a type for each field. Each of these fields contains 
data that is always accessed in the same way (see §4.3.2). 


Example of a record-type: 


record 
year: integer; 
month: 1...12; 


day: 1..31 
end 
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A variant-part consists of alternative field-lists of which only one is accessible at a given 
time. Each alternative field-list is called a variant. 


variant-part 


variant 


field-list 


tag-field-type 
ordinal-type-identifier 


Each variant is preceded by one or more constants. All of the constants must be distinct and 
must be of an ordinal-type that is compatible with the tag-type (see §3.5). 


The variant-part allows for an optional identifier that denotes a tag-field. If a tag-field is pre- 
sent, it is considered a field of the fixed-part. The value of the tag-field indicates which vari- 
ant is active, and thus which variant’s fields are accessible at a given time. If there is no tag- 
field explicitly given, then all fields in all variants are always accessible, i.e. the active variant 
is the one containing the field most recently referenced. 


It is an error to alter the value of a tag-field while a reference to a field of the active variant 
exists. Whenever the value of the tag-field changes, the values of all of the fields in the newly 
active variant are undefined. When the value of the tag-field is undefined, the values of all 
fields in all variants of the corresponding variant-part are undefined. 


Note: All of the variants of a variant-part share the same region of memory 
within a record variable. This is because only one particular variant is ever in 
use at a time (see also §10.1). 


It is not uncommon for Pascal programmers to use a variant-part with no explicit tag-field as 
a means of converting a value of one type to a value of another type, namely by assigning a 
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value into a field of one variant and referencing the corresponding field in another variant. 
For example: 


var 
r: record 
case boolean of 
false: (CharVal: char); 
true: (IntVal: integer) 


end; 
x.CharVal := 'W'; 
¢ i= r.Intval; 


However, this kind of access assumes a knowledge of the underlying representation of 
variables in memory, and is therefore not recommended. This sort of type coercion should be 
performed using the predefined functions chr and ord, or with type casts (see §5.4) which 
are guaranteed to do what you would expect. 


Examples of record-types with variants: 


record 
name, firstName: string[80]; 
age: 0..99; 
case married: boolean of 
true: (spousesName: string[80]) ; 
false: () 
end 


record 
x,y: real; 
area: real; 
case s: shape of 
triangle: ( side: real; 
inclination, anglel, angle2: angle); 
rectangle: ( sidel, side2 : real; 
skew, angle3: angle); 
circle: ( diameter: real) 
end 


Language Reference 17 


3.2.3 Set-Types 

A set-type has a range of values that is the powerset of some ordinal-type, called the base- 
type. In other words, each possible value of a set-type is a subset of the possible values of 
the base-type. 


set-type 
set (of ) ordinal-type 


Operators applicable to sets are specified in §5.1.4. §5.3 shows how set values are denoted in 
Pascal. 


The empty set (see §5.3) is a possible value of every set-type. 


3.2.4 File-Types 

A file-type is a structured-type consisting of a linear sequence of components that are all of 
one type, the component-type. The component-type may be any type that is nota file-type 
or a structured-type that contains a file-type component at any level of structuring. The 
number of components in a file-type variable is not fixed by the file-type declaration. 


abe) [ee > 


The standard file-type text denotes a packed file of characters organized into lines. Files of 
type text are supported by the specialized I/O procedures discussed in §9.4. 


§4.3.3 and §9 discuss methods of accessing file components, 


3.2.5 Object-Types 

An object-type is similar to a record-type (§3.2.2) except that in addition to fields, object- 
types can contain components called methods. A method is a procedure or function that 
operates on the object. 


An object-type can be a descendant of any other object-type. It inherits all of the fields and 
methods of its parent. A descendant object-type can defined new fields, new methods, and 
override inherited methods with its own implementation. 


Objects are created dynamically during program execution with the new and dispose 
procedures (§10.1.1 and §10.1.2). But instead of being identified by pointers, objects are 
identified by analogous values called references. 


A type identifier associated with an object type always denotes the reference type whose 
base type is that object type. 
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A variable of type object is not the object itself, but rather a reference to the object. So a 
variable of type object is called a reference variable. A reference variable is said to possess 
reference-type. Any number of reference variables can refer to the same object. 


Note: This is analogous to how pointers work: a variable of type “pointer to 


integer” is a pointer variable, not an integer. The pointer variable points to 
an integer. Several pointer variables can point to the same integer. 


object-type 
er 


field-list 


Lo [remortiee | 


heritage 


t+ © + ieee > O= 


method-list 


method-heading G) 


method-heading 


procedure-heading 


method-identifier 
procedure-identifier 


ne function-identifer 


reference-type-identifier 


Seferenee type Neent eet [raoneinier] 
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3.3 String-Types 


A string-type value is a sequence of characters that has a dynamic length attribute. The 
length is the actual number of characters in the sequence at any time during program execu- 
tion. 


A suring-type has a static size attribute that is an integral value in the range from 1 to 255. The 
size is a maximum limit on the length of any value of this type. If an explicit size attribute is 
not given for a string-type, then it is given a size of 255 by default. 


The current value of the length attribute of a string-type value is returned by the standard 
function length (see §10.5.1). A null-string is a string-type value with a length of zero. 


Note: Do not confuse the size with the length. 


string-type 


string 


U US , size-attribute zs gos, 
string-type-identifier 


size-attribute 
unsigned-integer 


The ordering relationship between any two string values is determined by lexical comparison 
based on the ordering relationship between character values in corresponding positions in 
the two strings. When the two strings are of unequal lengths, each character in the longer 
string that does not correspond to a character in the shorter one compares “higher”; thus the 
string value 'attribute' is greater than the value 'at'. Two strings must always have the 
same lengths to be equal; 'X ' (X followed by a space) is always greater than 'X" (just X). 


A null-string is only equal to another null-string and is less than every other possible string 
value. 


There are aspects of string-types that make it seem both a simple-type and a structured-type 
at the same time; it can therefore be considered neither. However, as explained in §4.3.1, in- 
dividual characters in a string can be accessed as if they were components of an array. 
Operators applicable to strings are specified in §5.1.5. Standard procedures and functions for 
manipulating strings are described in §10.5. 


3.4 Pointer-Types 


A pointer-type defines a set of values that point to dynamic-variables of a specified type 
called the base-type. 
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Pointer values are created by the standard procedure new (see §10.1.1), by the @ operator 
(see §5.1.6), and by the standard procedure pointer (see §10.2.6). 


pointer-type-identifier 
base-type 
type-identifier 


The base-type may be an identifier that has not yet been declared. In this case, it must be de- 
clared somewhere in the same type-declaration-part as the pointer-type (see §2.2.3). 


pointer-type 


The special symbol nil represents a standard pointer-valued constant that is a possible value 
of every pointer type. Conceptually, nil is a pointer that does not point to anything. 


§4.3.4 discusses the syntax for referencing the object pointed to by a pointer variable. 


3.5 Identical and Compatible Types 


Two types may or may not be identical, and identity is required in some contexts. Other 
limes, even if not identical, two types need only be compatible, and other times assign- 
ment-compatibility is required. 


3.5.1 Type Identity 
Identical types are required only in the following contexts: 


* For variable parameters, the actual and formal parameters must be identical types (see 
§7.3.2). 


* The result types of actual and formal functional parameters must be identical (see §7.3.4). 


* Value and variable parameters within parameter-lists of actual and formal procedural or 
functional parameters must be identical types (see §7.3.5). 


Two types, T; and To, are identical if one of the following is true: 


° 1, and T, are the same type-identifier. 
* 1, is declared to be equivalent to a type identical to Tp. 
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What the latter, somewhat circular statement implies is that T, need not be declared directly 
to be equivalent to Ty; thus the type-declarations 


Tl = integer; 


T2 = T1; 
T3 = integer; 
T4 = T2; 


result in Ty, Tp, T3, Tq, and integer all being identical types. 


However, the type-declarations 


TS 
T6 


set of integer; 
set of integer; 


do not result in Ts and T¢ being identical, since set of integer is nota type-identifier. 
Finally, note that two variables declared in the same declaration, as in 


vl, V2: set of integer 


are of identical type. However, if the declarations are separate then the above definitions 
apply. The declarations 


vl: set of integer; 
v2: set of integer; 
V3: integer; 
v4: integer; 


result in V3 and V4 being of identical type, but not V, and Vp. 


3.5.2 Compatibility of Types 

Compatibility between two types is sometimes required. Specific instances where type com- 
patibility is required are noted elsewhere in this manual. Type compatibility is, more impor- 
tantly, often a precondition of assignment-compatibility. 


Two types are compatible if any of the following are true: 


° Both types are identical. 

¢ Both types are real-types. 

¢ Both types are integer-types. 

© One type is a subrange of the other. 

¢ Both types are subranges of identical host-types. 

¢ Both types are set-types with compatible base-types. 
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¢ Both types are packed-string-types with the same number of components. 
* One type is a string-type and the the other is a string-type, packed-string-type, or 
char-type. 


3.5.3 Assignment-Compatibility 
Assignment-compatibility is required whenever a value is assigned to something, either ex- 
plicitly (as in an assignment-statemen) or implicitly (as in passing value parameters). 


A value V2 of type Tz is assignment-compatible with a variable V, of type T, (i.e. Vz :=Vo is 
permissible) if any of the following are true: 


* 1, and Tp are identical types and neither is a file-type or a structured-type that con- 


tains a file-type component at any level of structuring. 
¢ T and Tp are real-types and the value of type T, is within the range of possible val- 


ues of T. 

* T, isa real-type and Tp is an integer-type. 

* 1, and T, are compatible ordinal-types, and the value of type T» is within the range 
of possible values of T,. 

* 1, and T, are compatible set-types, and all the members of the value of type Tz are 
within the range of possible values of the base-ltype of T, . 

© 1, and T. are compatible packed-string-types. 

* TT, is a char-type and the value of type To is a string-type and has a length of 1. 

¢ T, isa packed-string-type with n components and the value of type T, is a string- 


type and has a length of n. 

* Tj isa string-type with a size of n and the value of type To is a string-type and has a 
length less than or equal to n. 

° Tj isa string-type with a size of n and the value of type Tp is a packed-string-type 
with a number of components less than or equal to n. 

* T, is a string-type and T> is a char-type. 

* Tp, is a reference-type that inherits from T. 


Itis an error if assignment-compatibility is required and none of the above is true. 
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3.6 The Type-Declaration Part 


Any program, procedure, or function that declares types contains a type-declaration-part, 


as shown in §2. 


Example of a type-declaration-part: 


type 

count = integer; 
range = integer; 
color = (red, yellow, green, blue); 
sex = (male, female); 
year = 1900..1999; 
shape = (triangle, rectangle, circle); 
card = array[1..80] of char; 
str = string[80]; 
polar = record 

r: real; 

theta: angle 

end; 


person = “personDetails; 
personDetails = record 


name, firstName: 


age: integer; 


married: boolean; 


father, child, 
case s: sex of 


sibling: person; 


male: (enlisted, bearded: boolean) ; 
female: (pregnant: boolean) 


end; 
people = file of personDetails; 
intfile = file of integer 


In the above example count, range, and integer denote identical types. The type year 
is compatible and assignment-compatible with, but not identical to, the types range, count, 


and integer. 


4.0 Variables 


4.1 Variable-Declarations 


A variable-declaration consists of a list of identifiers denoting new variables, followed by 


their type. 


variable-declaration 
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The occurrence of an identifier within the identifier-list of a variable-declaration declares it as 
a variable-identifier for the block in which the declaration occurs. The variable can then be 
referenced throughout the remainder of that block, except as specified in §2.2.2. 


Examples of variable-declarations: 


X,yY,z: real; 

i,j: integer; 

k: 0:22.97 

P,q,xr: boolean; 

operator: (plus, minus, times); 
a: array[0..63] of real; 

c: color; 

f: file of char; 

huel,hue2: set of color; 

pl,p2: person; 

m,ml,m2: array[1..10,1..10] of real; 
coord: polar; 

pooltape: array[1..4] of tape 


4.2 Variable-References 


A variable-reference denotes either an entire variable, a component of a structured or 


string-type variable, a dynamic-variable pointed to by a pointer-type variable, or the file- 
buffer of a file-type variable. 


variable-reference 


variable-identifier 


variable-identifier 
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4.3 Qualifiers 


As shown above, a variable-reference is a variable-identifier followed by zero or more quali- 
fiers. Each qualifier modifies the meaning of the variable-reference. 


index 
: , field-designator = 


As an example, an array identifier with no qualifier is a reference to the entire array-variable: 


qualifier 


xResults 


If the array-identifier is followed by an index, this denotes a specific component of the array: 


xResults[current+1] 


If the component is a record, the index may be followed by a field-designator; in this case the 
variable-reference denotes a specific field within a specific array component. 


xResults[current+1] .link 


If the field is a pointer, the field-designator may be followed by the symbol * to distinguish 
between the pointer field and the dynamic-variable being pointed to: 


xResults[(current+1] .link* 


If the object of the pointer is an array, another index can be added to denote a component of 
this array: 


xResults[current+1] .link* [i] 


and so on... 


4.3.1 Arrays, Strings, and Indices 
A specific component of an array variable is denoted by a variable-reference that refers to the 
array variable, followed by an index that specifies the component. 


249 


THINK’s Lightspeed Pascal 


250 


A specific character within a string variable is denoted by a variable-reference that refers to 
the string variable, followed by an index that specifies the character position. 


“a expression ‘ 


Examples of indexed arrays: 


index 


Each expression in the index selects a component in the corresponding dimension of the ar- 
ray. The number of expressions must not exceed the number of index-types in the array dec- 
laration. It is an error if the result of each expression is not assignment-compatible with the 
corresponding index-type. 


In indexing a multi-dimensional array, you can use either multiple indexes or multiple ex- 
pressions within an index. The two forms are equivalent. For example, 


m[i} [3] 
is equivalent to 
m(i,3j] 


A string value can be indexed by only one index expression, whose value must be in the 
range 1. .n, where n is the current length of the string value. The effect is to access one 
character of the string value, and the type of the character value accessed is char. 


Any value assigned to a component-variable of an array or string must be assignment-com- 
patible with the component-type. 


When a string value is manipulated by assigning values to individual character positions, the 
length of the string is not affected. It is an error to access a character position in a string vari- 
able with an index less than one or greater than the length of the string variable. For exam- 
ple, suppose that st rval has been declared as follows: 


strval: string[10]; 
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and that the assignment: 


strval := 'abcde'; 


has been performed. A reference to: 


strval[0] 


would be an error since the reference contains an index less than 1. Likewise, a reference to: 


strval[6] 


would be an error since the index is greater than the current length of the string. Note that 
these references would still be errors even if they occurred on the left-hand side of an as- 
signment statement. To add a character or string to the end of another string, or to manipu- 
late strings in other ways, use the standard procedures described in §10.5. 


Note also that, when a program, procedure, or function block is entered, the length of a 
string variable is initially undefined. Therefore, the manipulation of string variables with in- 
dexes before string values have been assigned to these variables can lead to unpredictable 
results, 


4.3.2 Records and Field-Designators 
A specific field of a record variable is denoted by a variable-reference that refers to the record 
variable, followed by a field-designator that specifies a field of the record. 


field-designator 
o 


Examples of field-designators: 


p2*.pregnant 
coord.theta 


Itis an error if the field-designator refers to a field in a variant that is not active (see §3.2.2). 


Note that a field-designator need not be preceded by a variable-reference to its containing 
record in a statement within a with statement (see §6.2.4). 


Fields of an object are accessed with a reference variable (§3.2.5) rather than with a record 
variable. You can leave out the reference variable and the “.” inside a with statement. You 
can also leave out the reference variable in a method block; in this case it is the same as 


having written self. before the field name (see §6.1.2 and §7.3.6). 
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4.3.3 File-Buffers 
Although a file-variable may have any number of components, only one component is 
accessible at any time. The position of the current component in the file is called the current 


file position. Program access to the current component is via a special variable associated 
with the file, called a file-buffer. 


The file-buffer is implicitly declared when the file variable is declared. If £ is a file variable 
with components of type t, then the associated file-buffer is a variable of type t . 


The file-buffer associated with a file variable is denoted by a variable-reference that refers to 
the file variable, followed by the * symbol. Thus, the file-buffer of file £ is referenced by £*. 


§9 describes standard procedures that move the current file position within the file and to 
transfer data between the file-buffer and the current file component. 


4,3.4 Pointers, Reference-Variables, and Dynamic-Variables 
The value of a pointer variable is either nil, or a value that points to a dynamic-variable. 


The dynamic-variable pointed to by a pointer variable is denoted by a variable-reference that 
refers to the pointer variable followed by the * symbol. 


Dynamic-variables and pointer values that point to them are created by the standard proce- 
dure new (see §10.1.1). Additionally, the @ operator (see §5.1.6) and the standard procedure 
pointer (see §10.2.6) may be used to create pointer values that are not in fact pointers to 
dynamic-variables, but that will be treated as such. 


The constant nil (see §3.4) does not point to any object. It is an error if you access a dy- 
namic-variable when the pointer's value is undefined or is nil. 


Examples of references to dynamic-variables: 


p1* 
pl*.sibling* 


Note: Although the * symbol is used to reference both file-buffers and dy- 
namic-variables, this does not mean that a file variable can be treated like a 
pointer. Specifically, ord (£), where f is a file variable reference, does not 
yield an address value (see §10.4.1). Itis, in fact, an error. 


A variable of type object is a reference variable. There is no way to reference the object 
itself, only the fields of an object. That is, you can’t use the * operator to access the object. 
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5.0 Expressions 


Expressions consist of operators and operands. Most operators in Pascal are binary, i.e. 
they take two operands; the rest are unary and take only one operand. The binary operators 
and their operands are denoted in the common algebraic fashion: the operands are given 
with the operator to act upon them in between, e.g., a+b. A unary operator is always imme- 
diately followed by its operand. 


When more complex expressions are written, certain rules must be applied to determine 
which operands are associated with which operators. For instance, the expression: 


atb*c 


can be interpreted as either (a+b) *c or at+(b*c). The precedence rules makes the in- 
terpretation unambiguous: 


¢ When an operand appears between two operators of different precedence, it is bound 
to the operator with the higher precedence. 

° When an operand is written between two operators of the same precedence, it is 
bound to the operator to the left. 

¢ A parenthesized expression is always evaluated before it is applied as an operand. 


Table 5-1 gives the precedence of the binary and unary operators: 


Table 5-1 
Precedence of 
Operators 


* di 
snultsplying" operators 
, 


relational operators 


Thus, a+b*c is interpreted as a+ (b*c), since * has a higher precedence than +, and a+b- 
c is interpreted as (a+b) -c, since + and — have the same precedence. 


The range of an operator is not infinite. For instance, if a, b, and c are integer-type integer 
values, and if at+b yields a value greater than maxint, then the evaluation (a+b) -c will 
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result in an error whereas at+ (b-c) may not. Whenever the order of evaluation of Operators 
is critical, or is otherwise in doubt, parentheses may always be used to force a specific order. 


Also be aware that, because the relational operators have the lowest precedence, an ex- 
pression such as 


asb or c<d 

is wrong because the precedence rules interpret the expression as 
a< (borec) <d 

which is not a valid expression (see below). Thus, such an expression must be written as 
(a<b) or (c<d) 


The precedence rules are implicit from the syntax for expressions, which are built up from 
factors, terms, and simple-expressions. 


The syntax for a factor allows the unary operators @ and not to be applied to a value: 


factor 


expression 


type-cast 
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A function-call activates a function, and denotes the value returned by the function (see 
§5.2). A set-constructor denotes a value of a set-type (see §5.3). An unsigned-constant has 


the following syntax: 
(ae 
quoted-string-constant 
constant-identifier 
POP eee a 


xt {variable-reference} 

@x {pointer to a variable} 

15 {unsigned-constant} 

(x+yt+z) { sub-expression} 

sin (x/2) {function-call} 

[CAS 9E', “Ma's ct£'] {set-constructor}) 
not p {negation of a boolean} 


unsigned-constant 


Examples of factors: 


The syntax for a term allows the “multiplying” operators to be applied to factors: 


term 
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Examples of terms: 


x*y 

iy ti=d) 

p and q 

(x <= y) and (y < z) 


The syntax for a simple-expression allows the “adding” operators and signs to be applied 
to terms: 


simple-expression 


Examples of simple-expressions: 


er oy 

= 

huel + hue2 
it 3 +1 
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The syntax for an expression allows the relational operators to be applied to simple- 
expressions: 


expression 


simple-expression 


= Bee simple-expression & 


Examples of expressions: 


5.1 Operators 
This section describes the Pascal arithmetic, relational, and address operators. 


5.1.1 Binary Operators: Order of Evaluation of Operands 
The order in which the operands of a binary operator are evaluated is unspecified. 


A function, in the normal case, simply returns a value. However, a function may also alter the 
value of variables as a side-effect. Therefore if a function is one operand of a binary operator, 
and if it modifies the value of the other operand, then the evaluation of the operator may lead 
to unpredictable results. For instance, if a call to a function f (x) modifies the value of x, 
then the evaluation of x+f£ (x) may yield an unexpected result depending on whether or 
not f (x) is evaluated before the x to the left of the +. 
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5.1.2 Arithmetic Operators 


The types of operands and results for arithmetic binary and unary operations are shown in 
Tables 5-2 and 5-3 respectively. 


Table 5-2 
Binary Arithmetic 


Operations 
addition 


integer integer} integer 
integer longint| longint 
longint longint} longint 
multiplication | real-type extended 


/ division integer-type or extended 
real-type 


integer 
longint 
longint 


subtraction 


integer integer 
integer longint 
longint longint 


division with 
integer 


integer integer | integer 
modulo integer longint | longint 
longint longint |longint 


Note: The symbols +, -, and * arealso used as set 
operators (See Section 5.1.4). 
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Table 5-3 
Unary Arithmetic Operations (Signs ) 


identity integer integer 


San TONGint longint 
sign-negation real-type extended 


Any operand whose type is subr, where subr is a subrange of some ordinal host-type 
ordtyp, is treated as if it were of type ordt yp. Consequently, an expression that consists of 
a single operand of type subr is itself of type ordtyp. 


If both operands of the addition, subtraction, or multiplication operators are of the integer- 
type integer, the result is always of type integer and has a value determined by the 
normal mathematical rules for integer arithmetic. It is an error if the value of the result is out- 
side the range -maxint-1..maxint. 


If one or both operands of the addition, subtraction, or multiplication operators are of the in- 
teger-type Longint, the result is always of type longint and has a value determined by 
the normal mathematical rules for integer arithmetic. It is an error of the value if the result is 
outside the range -maxlongint-1..maxlongint. 


If one of the operands of the addition, subtraction, or multiplication operators is of a real- 
type, the result is always of type extended and has a value that is an approximation of the 
normal mathematical result. It is an error if the result is outside the range of values repre- 
sentable with the real-type ext ended (see §3.1.2). 


Note: See Apple Numerics Manual, Second Edition (Addison-Wesley) for 
more information on all arithmetic operations with operands or results of a 
real-type. 


If the operand of the identity or sign-negation operator is of the integer-type integer, the 
result is always of type integer and the absolute value of the result is always identical to 


the absolute value of the operand. 


If the operand of the identity or sign-negation operator is of a real-type, the result is always of 
type extended and the absolute value of the result is always identical to the absolute value 
of the operand. 
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If the operand of the identity or sign-negation operator is of the integer-type longint, the 
result is always of type Longint and the absolute value of the result is always identical to 
the absolute value of the operand. 


The value of i/3 is always of type extended and has a value that is an approximation of 
the normal mathematical result. It is an error if the result is outside the range of values repre- 
sentable with the real-type ext ended (see §3.1.2). It is an error if 3=0. 


If the operands of the div operator are of the integer-type integer, the result is always of 
type integer, and the value of i div j is the mathematical quotient of i/3, rounded to- 


ward zero. It is an error if j=0. 


If one or both of the operands of the div operator are of the integer-type longint, the re- 
sult is always of type longint, and the value of i div 3 is the mathematical quotients of 
i/j, rounded toward zero. It is an error if j=0. 


The mod operator is defined as: 


imod j = i - (i div 4) * j 


5.1.3 Boolean Operators 
The types of operands and results for Boolean operations are shown in Table 5-4. 


Table 5-4 
Boolean Operations 


| Operation | Operand Types Type of Result 


eo 
and boolean boolean 
not 


conjunction 
The result of a boolean operation is determined by the normal rules of boolean logic, €.g.a 
and b evaluates to true if and only if both a and b are true. 


negation 


Boolean operators are somewhat unique in that the result of the operation may often be 
determined by the examination of only one operand. For example, the expression 


(b<>0) and (a/b>10) 
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is known to have the value false if b=0 regardless of the value of a. However, the eval- 
uation of the subexpression (a/b>10) may or may not be performed in the evaluation of 
this expression. It is therefore best to assume that it will and avoid this kind of expression. On 
the other hand, if an operand of a boolean expression is a function with side-effects (i.e. it 
modifies a variable as well as returns a value), there is no guarantee that the function will be 
activated if the result of the operation can be determined solely by the evaluation of the other 
operand. It is therefore best to also avoid such expressions. 


5.1.4 Set Operators 
The types of operands and results for set operations are shown in Table 5-5. 


Table 5-5 
Set Operations 


Operator] Operation | Operand Types Type of Result 


union 


compatible 


difference set-types (see below) 


intersection 


The order of evaluation of member-groups and of expressions within member-groups is un- 
specified, 


The results of the set operations are determined by the normal rules of set logic. 


¢ An ordinal value c is in the set a+b if and only if c is in a or in b. 
e An ordinal value c is in the set a-b if and only if c is in a and not in b. 
¢ An ordinal value c is in the set a*b if and only if c is in a andinb. 


Given the result of a set operation, if the smallest ordinal value that is a member of that result 


is a and if the largest ordinal-value that is a member of the result is b, then the type of the re- 
sultisset of a..b. 
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5.1.5 Relational Operators 
The types of operands and results for relational operations are shown in Table 5-6. 


Table 5-6 
Relational Operations 


equal compatible simple, 

pointer, set, string 
<> not equal or packed-string 
types 
| compatible BéolaaH 
simple, string, or 
packed-string types 
= compatible 
“"35~"TSapenset of | Set tyres 


5.1.5.1 Comparing Ordinals 
When the operands of =, <>, <, >, >=, ox <=are ofan ordinal-type, they must be of 
compatible types. The result is the mathematical relation of their ordinalities. 


5.1.5.2 Comparing Reals 
When one operand of=, <>, <, >, >=, or <=is ofa real-type, the other must be ofa 
real-type or an integer-type. The result is the mathematical relation of the values represented 
as extended type values. 


Because real-type values are only approximations, the results of these operations may not 
always be as expected. For instance, if aReal is a variable of type real and aDouble isa 
variable of type double, and if the assignments 


aReal := 1/3; 
aDouble := 1/3; 
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have been performed, then the relation aReal=aDouble will return false. This is because 
the value of aReal is a representation of 1/3 to only 7-8 decimal digits and the value of 
aDouble is a representation of 1/3 to 15-16 decimal digits. Since the decimal (and even the 
binary) representation of 1/3 is a repeating sequence of digits, the 8 low-order decimal digits 
of aDoub1e will differ from the corresponding digits of aReal (when converted to 
extended), which will always be zero. 


See Apple Numerics Manual, Second Edition (Addison-Wesley) for more information on 
relational operations with operands of real-type. 


5.1.5.3 Comparing Strings 

When the relational operators=, <>, <, >, >=, and > are used to compare strings 
(see §3.3), they denote lexicographic ordering according to the ordering of the Macintosh 
character set. Note that any two string values can be compared since all string values are 
compatible. Additionally, a char value is compatible with a string-type value, and when the 
two are compared, the char value is treated as a string-type value with length 1. When a 
packed-string-type value with n components is compared with a string-type value, it is 
treated as a string-type value with length n. 


5.1.5.4 Comparing Packed-Strings 

The relational operators=, <>, <, >, <=, and >= can also be used to compare two 
values of a packed-string-type if both have the same number of components. If that number 
of components is n, then the result is the same as if the values were string-type with each 
having a length of n. 


5.1.5.5 Comparing Sets 
If a and b are set operands, then 


¢ a=b is true if and only if every member of a is a member of b and every member of b 
is a member of a; otherwise, a<>b. 

* a<=b is true if and only if every member of a is also a member of b. 

* a>=b is true if and only if every member of b is also a member of a. 


Thus, a=b and a<>b denote the equivalence and non-equivalence of the sets a and b re- 
spectively, and a<=b and a>=b denote the inclusion of a in b and the inclusion of b in a re- 
spectively. 


5.1.5.6 Comparing Pointers 
The relational operators = and <> may be applied to compatible pointer-type operands. ‘wo 
pointers are equal if and only if they point to the same object. 


5.1.5.7 Testing Set Membership 

The in operator yields the value t rue if the value of the ordinal-type operand is a member 
of the set-type operand; otherwise it yields the value false. The type of the left operand 
must be compatible with the base-type of the right operand. 
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5.1.6 The @ Operator 
A pointer value that points to a variable, procedure, or function can be created with the @ 
operator. The operand and result types are shown in Table 5-7. 


@ is a unary operator taking a single variable-reference or a procedure or function identifier 
as its operand and computing the value of its pointer. The type of the value is equivalent to 
the type of nil, ie. it can be assigned to any pointer variable. 


Table 5-7 
Pointer Operation 


pointer variable-reference 
formation or procedure or 
function identifier 


same as nil 


The @ operator is not a standard feature of Pascal, and its indiscriminate use is not rec- 
ommended. It is intended to be used in conjunction with the Macintosh Toolbox routines. 


5.1.6.1 The @ Operator with a Variable 


For an ordinary variable (nota parameter), the use of @ is straightforward. For example, if we 
have the declarations 


type 
twochar = packed array[0..1] of char; 
var 


int: integer; 
twocharptr: “twochar; 


then the statement 


twocharptr := @int 


causes twocharptr to point to int. Now twocharptr% is a reinterpretation of the bit 
value of int as though it were a packed array[0..1] of char. 


The operand of @ cannot be applied to a component of a packed variable. 


5.1.6.2 The @ Operator with a Value Parameter 
When @ is applied to a formal value parameter, the result is a pointer to the location contain- 
ing the actual value, which is on a run time stack. Suppose that foo is a formal value 
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parameter in a procedure and fooptr is a pointer variable. If the procedure executes the 
statement 


fooptr := @foo 


then foopt r% is a reference to the value of foo. Note that if the actual-parameter is a vari- 
able-reference, foopt r* is not a reference to the variable itself; it is a reference to the value 
taken from the variable and stored on the stack. 


5.1.6.3 The @ Operator with a Variable Parameter 

When @ is applied to a formal variable parameter, the result is a pointer to the actual- 
parameter. Suppose that fum is a formal variable parameter of a procedure, fie is a variable 
passed to the procedure as the actual-parameter for fum, and fumptr is a pointer variable. 


If the procedure executes the statement 


fumptr := @fum 
then fumptr is a pointer to fie and fumpt r% is a reference to fie itself. 


5.1.6.4 The @ Operator with a Procedure or Function Identifier 

Itis possible to apply @ to a procedure or a function, yielding a pointer to the procedure’s or 
function’s entry-point. This pointer actually points to a jump table entry for the routine. 
See Chapter 13 for more information. 


THINK Pascal provides no mechanism for using such a pointer. The typical use for a proce- 
dure pointer is to pass it to a Macintosh Toolbox routine. The @ operator can not be applied 
to predefined, inline, Toolbox, or nested routines. 


5.2 Function-Calls 

A function-call specifies the activation of the function denoted by the function-identifier. The 
result returned by the function activation is subsequently used as an expression value. If the 
corresponding function-declaration contains a list of formal-parameters, then the function-call 
must contain a corresponding list of actual-parameters. Each actual-parameter is substituted 
for the corresponding formal-parameter as described in §7.3. 


function-call 


function-identifier 


method-desginator 


actual-parameter-list 


Note: method-designator is defined in §6.1.2 
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actual-parameter-list 


wu actual-parameter iz 


actual-parameter 


expression 


variable-reference 


lad procedure-identifier é 
6 


unction-identifier 


A function-identifier is any identifier that has been declared to denote a function. 


Examples of function-calls: 


sum(a, 63) 
ged (147,k) 
sin (x+y) 
eof (f) 

ord (f£*) 


5.3 Set-Constructors 


A set-constructor denotes a value of a set-type, and is formed by writing expressions within 
(brackets] . Each expression denotes a value of the set. 


set-constructor 


\ —» [aessoraecir PA 


member-group 


expression 


expression 
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The notation, [ ] denotes the empty set, which is assignment-compatible with every set- 
type. Any member-group x. . y denotes as set members all values in the range x. .y. If the 
value of x is greater then the value of y, then x. .y denotes no members and [x. .y] 
denotes the emply set. 


All expression values in the member-groups of a particular set-constructor must be of com- 
patible ordinal-types. If a is the smallest ordinal-value in the resulting set, and if b is the 
largest ordinal-value in the resulting set, then the base-type of the resulting set is a. .b. 


Examples of set-constructors: 


{red, c, green] 
[lg Sy LO. dmod: 02). 23)) 
FTAT 2 TOM, Sats. Val, chelzcode)') 


5.4 Type-Casts 
Type casting (also called type coercion) provides a way to change the type of an expression 
to another type. 


type-cast 
© © 


For ordinal and pointer types, the result of this operation is an expression of type type-iden- 
tifier whose (ordinal) value is obtained by converting the original expression. This conver- 
sion may involve truncation or extension of the original value if the storage size of the ex- 
pression is changed. 


For non-ordinal types, the result of this operation is an expression of type type-identifier 
whose internal representation (i.e., the pattern of bits which comprise its value) is the same 
as the internal representation of the original expression. In particular, the storage size of a 
(non-ordinal) expression may not be changed by a type cast. 


A value of reference-type can be coerced to another reference-type in the same domain. 


Examples of type-casts: 


boolean (1) 

ptr (longint (p)+1) 
PEE KHL) 

longint (@proc) 
color (x) 
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6.0 Statements 


Statements denote algorithmic actions, and are executable. They can be prefixed by labels 
and a labeled statement can be referenced by a goto-statement. 


ia simple-statement aa 
structured-statement 


label 


A digit-sequence used as a label must be in the range 0..9999, and must first be declared as 
described in §2.1. 


statement 


6.1 Simple-Statements 
A simple-statement is a statement that does not contain any other statement. 


simple-statement 
assignment-statement 
: | procedure-statement - 
goto-statement 


6.1.1 Assignment-Statements 
The syntax for an assignment-statement is as follows: 


assignment-statement 
LS variable-reference 5 
function-identifier 


The assignment-statement can be used in two ways: 


expression 


* To replace the current value of a variable with a new value specified by an 
expression. 
* To specify an expression whose value is to be returned by a function. 
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The expression must be assignment-compatible with the type of the variable or the result- 
type of the function as described in §3.5.3. 


It is not specified whether the variable-reference is evaluated before or after the evaluation of 
the expression. However, once the reference is established, it is not altered by the remaining 
execution of the assignment-statement. Thus, the outcome of 


alx] <= £ (x) 


depends on whether £ modifies x and, if so, whether £ (x) is evaluated before or after 
Edie ale 


Examples of assignment-statements: 


* 
i 


yrz; 
= (1<=i) and (i<100); 
2. g= sqri(k) — (i* 9) 
huel := [blue,succ(c) ] 
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6.1.2 Procedure-Statements 

A procedure-statement specifies the activation of the procedure denoted by the procedure- 
identifier. If the corresponding procedure-declaration contains a list of formal-parameters, 
then the procedure-statement must contain a corresponding list of actual-parameters, Each 
actual-paramceter is substituted for the corresponding formal-parameter as described in §7.3. 


A method-designator activates the method specified by the method-identifier (§3.2.5) of an 
object-type referenced by the reference-variable. The actual method activated is specified by 
the run-time type of the object. When the method is activated, the object is passed as an 
implicit formal parameter called se1£ (see §7.3.6) of the type corresponding to the object 
whose method was activated. 


You can omit the reference variable and the “.” within a with statement that lists the 
reference variable (see §4.3.2 and §6.2.4). You can also leave out the reference variable ina 
method block; in this case it is the same as having written self. before the field name. 


You'll usually use the inherited keyword when you override a method (see §3.2.5). It can 
only be used in a method block. When it appears before a method-identifier, it causes sel£ 
to be the implicit actual parameter to the called procedure. The method activated is always 
the method inherited from the parent object; any overrides are ignored. 


procedure statement 


procedure-identifier 


method-desginator 


z , actual-parameter-list z 


A method-designator activates the method specified by the method-identifier (§3.2.5) of an 
object. The run-time type of the object determines which method is activated. 


method-designator 


; reference-variable . em 


inherited 


Note: The order in which actual parameters are evaluated and bound to 
their formal parameters is unspecified. 


method-identifier 
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Examples of procedure-statements: 


PrintHeading; 
Transpose(a,n,m); 
Bisect (fct,-1.0,+1.0,x) 


6.1.3 Goto-Statements 
A goto-statement causes the statement prefixed by the label that is referenced in the goto- 
statement to be the next statement executed. 


— >see) —o[ aver |} 


Note: The constants that introduce cases within a case-statement (see 
§6.2.2.2) are not labels, and cannot be referenced in goto-statements. 


A goto-statement G can goto a labeled statement S if and only if one of the following is true: 


S is a statement that contains G. For example: 


12 2 . then 
2 begin 
3% begin 
goto {1, 2 and 3 are legal, 4 is not} 
end 
end 
else 
4: begin 
end 
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S is a statement of a statement-list that contains G. For example: 


begin 
ds ih 
begin 
2% ; 
begin 
goto {1, 2, 3, and 4 are legal, 5 is not} 
end ¥ 
a ; 
end 
4: ; 
end; i 
begin 
De: Ss, 
end 


272 


Language Reference 17 


S is a statement in a block that contains the block containing G, provided that S is a statement 
of the outermost statement-list of its block. For example: 


program a(...); 
procedure b; 
procedure c; 
begin 
goto {2 and 4 are legal; 1 and 3 are not} 
end; 


procedure d; 


begin 
1s ro 
end; 
begin { b } 
2: ote 
begin 
Bg 
end 
end; 
begin { main } 
4: 


end. 


When the destination of a goto is in a block b that does not contain the goto, every block 
activation (see §2.3) that has occurred since the most recent activation of b is terminated. 


6.2 Structured-Statements 


Structured-statements are made up of of other statements that are to be executed either 
conditionally (conditional-statements), repeatedly (repetitive-statements), or in sequence 
(compound-statement or with-statemenv). 


compound-statement 
ne conditional-statement | 
SS 
with-statement 


structured-statement 
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6.2.1 Compound-Statements 
The compound-statement specifies that its component statements are to be executed in the 
same sequence as they are written. The semicolon is a statement separator, not terminator. 


compound-statement 


statement-list (end ) 
statement-list 
ae 


Example of compound-statement: 


begin 
z x; 
x f= y; 
y i= z 
end 


An important use of the compound-statement is to group more than one statement into a 
single statement in contexts where the Pascal syntax only allows one statement. The symbols 
begin and end act as “statement brackets.” Examples of this will be seen in §6.2.3.2. 


6.2.2 Conditional-Statements 
A conditional-statement selects for execution a single one (or none) of its component 
statements. 


conditional-statement 


if-statement 


case-statement 


Language Reference 17 


6.2.2.1 If-Statements 
The syntax for if-statements is: 


if-statement 


expression 


statement 


any sae 


The expression must yield a result of the standard type boolean. If the expression yields the 
value t rue, then the statement following the then is executed. 


If the expression yields false, and the else part is present, the statement following the 
else is executed; if the else part is not present, then execution proceeds with the next 


statement following the if statement. 


The syntactic ambiguity arising from something like: 


if el then if e2 then sl else s2 


is resolved by interpreting it as being equivalent to: 


if el then 
begin 
if e2 then 
sl 
else 
s2 
end 
rather than: 
if el then 
begin 
if e2 then 
sl 
end 
else 
s2 
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In other words, an else is always associated with the closest if that is not already 
associated with an else. 


Examples of if-statements: 


if x < 1.5 then 
2 23 =hy 
else 
223 1.5 


if pl <> nil then 
pl := pl*.father 


6.2.2.2 Case-Statements 

The case-statement contains an expression (the selector) and a list of statements. Each 
statement must be prefixed with one or more constants (called case-constants), or with the 
reserved word otherwise. All the case-constants must be distinct and must be of an 


ordinal-type that is compatible with the type of the selector. A case-constant can be of type 
longint. 


case-statement 


otherwise-clause 


a 
otherwise-clause 
S 


The case-statement specifies execution of the statement prefixed by a case-constant equal to 
the current value of the selector. If no such case-constant exists and an otherwise part is 


para 


case 


Languag 


present, the statement following the word otherwise is executed; if no otherwise part is 
present, it is an error. 


Examples of case-statements: 


case operator of 


plus: x 3:= xty7 
minus: x := x-y; 
times: x := x*y 


end 


case i of 


Ls a f= stn(s)s 

Bip Gas LAD. SS. SE eositss) & 

3..7: x := exp(x); 
otherwise 

x := In(x) 


end 


6.2.3 Repetitive-Statements 
Repetitive-statements specify that certain statements are to be executed repeatedly. 


repeat-—statement 
Br while-statement mal 


for-statement 


repetitive-statement 


6.2.3.1 Repeat-Statements 
A repeat-statement contains an expression that controls the repeated execution of a 
sequence of statements contained within the repeat-statement. 


repeat-statement 


The expression must yield a result of the standard type boolean. The statements between 
the symbols repeat and until are repeatedly executed in sequence until, at the end of a 
sequence, the expression yields the value true. The sequence of statements is executed at 
least once, because the expression is evaluated after the execution of each sequence. 


eference 17 
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Examples of repeat-statements: 


repeat 

i mod j; 
37 

k 

until j = 0 


repeat 
process (f*); 
get (f) 

until eof (f) 


6.2.3.2 While-Statements 
A while-statement contains an expression that conuols the repeated execution of a 
statement (which may be a compound-statement). 


while-statement 
Go acme | 


The expression must yield a result of the standard type boolean. It is evaluated before the 
contained statement is executed. The contained statement is repeatedly executed as long as 
the expression yields the value true. If the expression yields false at the beginning, the 
statement is not executed. 


The while-statement: 


while b do 
body 


is equivalent to: 


if b then 
repeat 
body 
until not b 
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Examples of while-statements: 


while a[i] <> x do 
io:= itl 


while i>0 do 


begin 
if odd(i) then 
Zz s> Ska 
2 see diy 2 
x := sqr(x) 
end 


while not eof(f) do 
begin 
process (f£*); 
get (f£) 
end 


6.2.3.3 For-Statements 
The for-statement causes a statement (possibly a compound-statement) to be repeatedly 
executed while a sequence of values is assigned to a variable called the control-variable. 


statement 


Rear 


control-variable 

variable-identifier 
initial-value 
ee o[ceresoion > 


final-value 
expression 


17 


279 


THINK’s Lightspeed Pascal 


280 


The control-variable must be a variable-identifier (without any qualifier) denoting a variable 
that is declared to be local to the block containing the for-statement. The control-variable 
must be of an ordinal-type, and the initial and final values must be of a type assignment- 
compatible with this type. 


On entering a for-statement, the initial-value and the final-value are determined once (and 
only once) for the remainder of the execution of the for-statement. 


Loosely speaking, the statement contained by the for-statement is executed once for every 
value in the range initial-value. .final-value. With a for-statement using to, the 
control-variable has the value initial-value the first time, succ (initial-value) the 
second time, and so on. If the initial-value is greater than the final-value, then the contained 
statement is not executed. With a for-statement using downto, the control-variable has the 
value initial-value the first ime, pred (initial-value) the second time, and so on. If the 
initial-value is less than the final-value, then the contained statement is not executed. 


Itis an error if the value of the control-variable is altered by execution of the contained 
statement. After a for-statement is executed, the value of the control-variable is undefined, 
unless the execution of the for-statement was terminated by a goto out of the for-statement. 


Apart from these restrictions, the for-statement: 


for v := el to e2 do 
body 


is equivalent to: 


begin 
temp1 el; 
temp2 := e2; 
if templ <= temp2 then 
begin 
vo 3= tempi; 
body; 
while v <> temp2 do 
begin 
v 3:= succ(v); 
body 
end 


end 
end 
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and the for-statement: 


for v := el downto e2 do 
body 


is equivalent to: 


begin 
temp1 el; 
temp2 := e2; 
if templ >= temp2 then 
begin 
v := templ; 
body; 
while v <> temp2 do 
begin 
v := pred(v); 
body 
end 


end 
end 


where temp1 and temp2 are auxiliary variables of the host-type of the variable v that do not 
occur elsewhere in the program; they are used to resolve the expressions e1 and e2 upon 
entering the statement’s body. 


Examples of for-statements: 


for i := 2 to 63 do 
if afi] > max then 
max := a[i] 
for i := 1 ton do 
foxr j z= 1 ton do 
begin 
x -F= (02 
for k := 1 to n do 
x := x + ml(i,k)*m2[(k,j]; 
m[{i,j] :=x 
end 
for c := red to blue do 
q(c) 
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6.2.4 With-Statements 
The syntax for a with-statement is 


with-statement 
= with-variable-list } 
with-variable-list 


i‘ with-variable Ei 


record-variable 


reference-variable 


The occurrence of a record-variable-reference or a reference-variable in a with-statement 
affects the way the compiler processes variable-references within the statement following the 
word do. Within a with-statement, fields of the record-variable or the reference-variable can 
be referenced directly by their field-identifiers, without making explicit reference to the 
record-variable. The same is true for methods of reference-variables. 


[eeaeenane J 


— 


with-variable 


Example of a with-statement: 


with date do 
if month = 12 then 


begin 
month := 1; 
year := year + 1 
end 
else 
month := month + 1 
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This is equivalent to: 


if date.month = 12 then 


begin 
date.month := 1; 
date.year := date.year +1 
end 
else 
date.month := date.month + 1 


Within a with-statement, each variable-reference is checked to see if it can be interpreted as a 
field of the record. If so, it is always interpreted as such, even if a variable with the same 
name is accessible also, For instance, suppose that we have the following declarations: 


type 
recTyp = record 
foo: integer; 
bar: real; 
end; 


var 
bar: recTyp; 
foo: integer; 


The identifier foo can refer both to a field of the record variable bar and to a variable of 
type integer. In the statement 


with bar do 


begin 
foo := 36; 
bar := 2.5; 
end 


the bar between the with and the do is a reference to the variable bar, but foo is a 
reference to the field bar. foo, not the variable foo. Likewise, the reference to bar within 
this with-statement refers to bar. bar. 


The statement: 


with v1,V9, «=. Vp, do 


s 
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is equivalent to: 


with v,; do 
with vp do 


with v, do 
s 


Thus, if v, in the above statements is a field of both v, and vg, itis interpreted to mean 
V2-V_, and notvy.v,. 


If the selection of a variable in the record-variable-list involves the indexing of an array or the 
de-referencing of a pointer, these actions are executed only once before the component 
statement is executed. 


7.0 Procedures and Functions 


This section describes how to declare procedures and function in Pascal. It also describes 
how Pascal interprets parameters passed to these routines. 


7.1 Procedure-Declarations 


A procedure-declaration associates an identifier with a block as a procedure so that it can 
be activated by a procedure-statement (see §6.1.2). 


procedure-declaration 


procedure-heading ) procedure-body & 


procedure-body 


block 


Soom 
inline-body 


The procedure-heading specifies the identifier for the procedure, and the formal parameters 
Cif any). 
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procedure-heading 


procedure 


identifier 


| 


formal-parameter-list 


The syntax for a formal-parameter-list is given in §7.3. 


A procedure is activated by a procedure-statement (see §6.1.2), which gives the procedure’s 
identifier and any actual-parameters required by the procedure. The statements to be 
executed upon activation of the procedure are specified by the statement-part of the 
procedure’s block, If the procedure'’s identifier is used in a procedure-statement within the 
procedure’s block, the procedure is executed recursively (see §2.3). 


Example of a procedure-declaration: 


procedure ReadInteger(var f : text; var x : integer); 
var 
value, digit : integer; 


begin 
while (f* = ' ') and not eof(f) do 
get (f); 
value := 0; 
while (f* in ['0'..'9']) and not eof(f) do 
begin 
digit := ord(f*) - ord('0'); 
value := 10*value + digit; 
get (£) 
end; 
x := value 
end; 


7.1.1 Forward-Declarations 

A procedure-declaration that has the directive forward instead of a block is called a 
forward declaration. Somewhere after the forward declaration, the procedure is actually 
defined by a defining-declaration — a procedure-declaration that uses the same 
procedurc-identifier, but omits the formal-parameter-list, and includes a block. The forward 
declaration and the defining-declaration must be in the same procedure-and-function- 
declaration-part, but need not be contiguous; that is, other procedures or functions can be 
declared between them and can call the procedure that has been declared forward. This 
permits mutual recursion. 


The forward declaration and the defining-declaration constitute a complete declaration of the 


procedure. The procedure is considered to be declared at the place of the forward 
declaration. 
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Example of a forward declaration: 


procedure walter(m,n : integer); 
forward; 


procedure clara(x, y : real); 
begin 


walter(4, 5); 
end; 


procedure walter; 
begin 


clara(8.3, 2.4); 
end; 


7.1.2 External-Declarations 

A procedure-declaration that has the directive external instead of a block is called an 
external declaration. External procedures and functions are used to declare the Pascal 
interface to a separately compiled or assembled routine. The external code must be linked 
with the rest of the program before execution. 


Example of an external-declaration: 


procedure DoInits (num: integer) ; 
external; 


This means that DoInits is an external procedure that will be linked with the rest of the 
program before execution. 


Note: It is the programmer's responsibility to insure that the external 
procedure is compatible with the external declaration in the Pascal program. 


A unit (see §8.3) may declare a procedure in the interface-part and then implement this 
procedure by an external declaration. For example, 
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unit a; 
interface 
procedure foo (arg:integer); 
implementation 
procedure foo; 
external; 
end. 


This description of external procedures also applies to external functions. 
7.1.3 Inline-Declarations 


A procedure-declaration that has the word-symbol inline followed by one or more integer 
constants instead of a block is called an inline declaration. Inline procedures and functions 
are used to embed machine code in a Pascal program. 


inline-body 


inline constant 


When a procedure is normally called, code is generated that reserves one or two words of 
function result (if a function is being called), and pushes the procedure’s arguments Cif any). 
Then a JSR instruction is generated. By declaring a routine as inline, the compiler will 
cause the constants that follow the word-symbol inline to be generated in place of the JSR 
instruction, Each constant represents one word (16 bits) and is generated in the order given. 


Example of an inline-declaration: 


procedure trap (tos : longint); 
inline SA9ED; 


* Itis the programmer's responsibility to observe the proper rules for adjusting the 
stack, saving registers, etc. 

¢ An inline procedure declared in a unit’s interface section has no corresponding 
declaration in the implementation section. 

¢ A forward declaration or interface procedure declaration may not be later defined as 
an inline declaration. 


This description of inline procedures also applies to inline functions. 
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7.2 Function-Declarations 
A function-declaration serves to declare a part of the program that computes and returns a 


value of some type. 


function-declaration 


function-heading @ function-body (s) 


eH 
in-line body 


The function-heading specifies the identifier for the function, the formal parameters (if 
any), and the type of the function result. 


function-body 


function-heading 


ie formal-parameter-list ¥ 
result-type 
type-identifier 
indefinite-string-type 
indefinite-string-type 


The syntax for a formal-parameter-list is given in §7.3. 


result-type 
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A function is activated by the evaluation of a function-call (see §5.2), which gives the 
function's identifier and any actual-parameters required by the function. The function-call 
appears as an operand in an expression. The expression is evaluated by executing the 
function and, in effect, replacing the function-call with the value returned by the function. 


The statements to be executed upon activation of the function are specified by the statement- 
part of the function’s block. This block should normally contain at least one assignment- 
statement (see §6.1.1) that assigns a value to the function-identifier. The result of the function 
is the last value assigned. If no such assignment-statement exists, or if it exists but is not 
executed, the value returned by the function is undefined, which is an error. 


If the function's identifier appears as an operand in an expression within the function's block, 
the function is executed recursively. 


Examples of function-declarations: 


function max(a : vector; n : integer) : real; 
var 
real; 
integer; 
begin 
x := a[(l1l]; 
for i := 2 to n do 
if x < a[i] then 
2 2= ail; 
max := xX 
end; 
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function power(x : real; y : integer) : real; 
var 
w,zZ : real; 
ay : integer; 
begin 
Wol= x; 
Zo Ls 
i:i=y; 
while i > 0 do 
begin 
{z* (w**i) = x ** y } 
if odd(i) then 
Z3= ztw; 
i := i div 2; 
w := sqr(w) 
end; 
{im = eke oy 
power := z 
end; 


A function can be declared forward in the same manner as a procedure (see §7.1 above). This 
permits mutual recursion. 


7.3 Parameters 


A formal-parameter-list may be part of a procedure-declaration or function-declaration, or 
it may be part of the declaration of a procedural or functional parameter. 


If itis part of a procedure-declaration or function-declaration, it declares the formal 
parameters of the procedure or function. Each parameter so declared is local to the 
procedure or function being declared, and can be referenced by its identifier in the block 
associated with the procedure or function. 
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If it is part of the declaration of a procedural or functional parameter, it declares the formal 
parameters of the procedural or functional parameter. In this case there is no associated 
block and the identifiers of parameters in the formal-parameter-list are not significant (see 
§7.3.3 and §7.3.4 below). 


formal-parameter-list 
= parameter-declaration ‘ 
procedure-heading 


function-heading 


parameter-declaration 


parameter-type 


parameter-type 


Te type-identifier | 
indefinite-string-type 


There are four kinds of parameters: value parameters, variable parameters, procedural 
parameters, and functional parameters. They are distinguished as follows: 


e A parameter-group preceded by var is a list of variable parameters. 

¢ A parameter-group without a preceding var is a list of value parameters. 

e A procedure-heading or function-heading denotes a procedural or functional 
parameter; see §7.3.3 and §7.3.4 below. 


The type of a formal-parameter is denoted by either a type-identifier or the word-symbol 
string. Thus, to use a type such as array[0..255] of char asthe type ofa 
parameter, you must declare a type-identifier for this type: 


type 
charray = array[0..255] of char; 
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The identifier charray can then be used in a formal-parameter-list to denote the type. 


The interpretation of string as a parameter-type is described below. 


7.3.1 Value Parameters 

For a value parameter, the corresponding actual-parameter in a procedure-statement or 
function-call (see Sections 5.2 and 6.1.2) must be an expression, and its value must not be of 
file-type or of any structured-type that contains a file-type. The formal value parameter 
denotes a variable local to the procedure or function. The current value of the expression is 
assigned to the formal value parameter upon activation of the procedure or function. The 
actual-parameter must be assignment-compatible with the type of the formal value parameter 
(see §3.5.3). If the parameter-type is string, then the formal parameter is given a size 
attribute of 255. 


7.3.2 Variable Parameters 

For a variable parameter, the corresponding actual-parameter in a procedure-statement or 
function-call (see §5.2 and §6.1.2) must be a variable-reference. The formal variable parameter 
denotes this actual variable during the entire activation of the procedure or function. 


Within the procedure or function, any reference to the formal variable parameter is a 
reference to the actual-parameter itself. The type of the actual-parameter must be identical to 
that of the formal variable parameter. However, if the parameter-type is string, then any 
string-type is considered identical to it; the size attribute of the formal parameter is always the 
size attribute of the actual parameter. 


If the reference to an actual variable parameter involves indexing an array or finding the 
object of a pointer, these actions are executed before the activation of the procedure or 
function. 


Components of variables of any packed structured-type cannot be used as actual variable 
parameters. 


7.3.3 Procedural Parameters 

When the formal-parameter is a procedure-heading, the corresponding actual-parameter in a 
procedure-statement or function-call (see Sections 5.2 and 6.1.2) must be a procedure- 
identifier. The identifier in the formal procedure-heading represents the actual procedure 
during execution of the procedure or function receiving the procedural parameter. 
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Example of procedural parameters: 


program PassProc; 
var 
i: integer; 
procedure a(procedure x) ; 
begin 
write('About to call x '); 
x 
end; 


procedure b; 


begin 
write('In procedure b') 
end; 
function c(procedure x) : integer; 
begin 
x; 
c:=2 
end; 


begin {PassProc} 
a(b); 
i:= c(b) 
end. 


If the formal procedure has a formal-parameter-list, then the actual procedure’s declaration 
must also have a formal-parameter-list and both must be compatible (see §7.3.5). However, 
only the identifier of the actual procedure is written as an actual parameter; no formal or 
actual parameter-list is given. 
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Example of procedural parameters with their own formal-parameter-lists: 


program test; 
procedure xAsPar(y : integer); 
begin 
writeln('y=', y) 
end; 


procedure CallProc(procedure xAgain(z:integer) ); 
begin 

xAgain (1) 
end; 


begin {test} 
CallProc (xAsPar) 
end. 


If the procedural parameter, upon activation, accesses any non-local entity (by variable- 
reference, procedure-statement, function-call, or label), the entity accessed will be the one 
that was accessible to the procedure when the procedure was passed as an actual parameter. 


To see what this means, consider the following program taken from an example in the ANSI 
Pascal Standard (which is in turn taken from an early version of the Pascal Validation Suite): 


program t6p6p3p4 (output) ; 
var 
GlobalOne, GlobalTwo : integer; 


procedure dummy; 
begin 
writeln('fail4') 
end; 


procedure p(procedure f (procedure ff; procedure gg) ; 
procedure gq); 
var 
LocalToP : integer; 


procedure r; 
begin 
if GlobalOne = 1 then 
begin 
if (GlobalTwo <> 2) or (LocalToP <> 1) then 
writeln('faill') 
end 
else if GlobalOne = 2 then 
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begin 
if (GlobalTwo <> 2) or (LocalToP <> 2) then 
writeln('fail2') 
else 
writeln('pass') 


end 
else 
writeln('fail3'); 
GlobalOne := GlobalOne + 1 
end; 
begin {p} 
GlobalTwo := GlobalTwo + 1; 
LocalToP := GlobalTwo; 
if GlobalTwo = 1 then 
p(f,r) 
else 
£(g,r) 


end; 


procedure q(procedure f; procedure g); 
begin 
£; 


begin {program} 
GlobalOne 
GlobalTwo 
p(q, dummy) 
end. 


An explanation might make things clearer: 


1. At the call to p in the main program, GLobalOne=1 and GlobalTwo=0. 

2. Within p, the formal parameter £ corresponds to the actual procedure q and the 
formal g corresponds to the actual dummy. The values of GLobal Two and 
LocalToP both become 1. Because Global Two=1, p calls itself recursively. 

3. Within this second activation of p, the formal £ corresponds to the formal £ of the 
first activation, which corresponds to the actual q. The formal g corresponds to the 
actual r. The values of GLobalTwo and LocalToP now become 2. Because 
Global Two<>l1, this second activation of p now calls its formal parameter £, which 
is the actual procedure q. 

4. Within q, its formal parameter £ corresponds to the actual procedure r and the 
formal g also corresponds to the actual r. Procedure q now calls its formals £ and g, 
ie. x and r, and the program terminates after all the activations unwind. 


295 


THINK’s Lightspeed Pascal 


296 


It’s is what happens during the two calls to procedure r within procedure q that is critical. If 
this program runs correctly, it will print ‘pass’. For this to happen, the first call to r will occur 
while GlobalOne=1 and will expect LocalToP to be 1; the second call to r_ will occur 
while GlobalOne=2 and will expect Local ToP to be 2. Since there are no assignments to 
LocalToP within r or q, how can this be? 


LocalToP is not simply local to the procedure p, it is local to each activation of p. Since 
there are two activations of p, and since r is passed as a parameter in each activation of p, 
each r accesses the variable LocalToP thatis local to the activation in which it is passed. 
Since, in the first activation of p, the value of LocalToP is 1, that is the value the first 
execution of r sees when it accesses Local ToP. Since, in the second activation of p, the 
value of LocalToP is 2, that is the value the second execution of r sees. 


Predefined, inline, and Toolbox procedures can not be passed as procedural parameters. 


7.3.4 Functional Parameters 

When the formal parameter is a function-heading, the actual-parameter must be a function- 
identifier. The identifier in the formal function-heading represents the actual function during 
the execution of the procedure or function receiving the functional parameter. 


Functional parameters are exactly like procedural parameters, with the additional rule that 
corresponding formal and actual functions must have identical result-types. 


7.3.5 Parameter List Compatibility 
Parameter list compatibility is required of the parameter lists of corresponding formal and 
actual procedural or functional parameters. 


Two formal-parameter-lists are compatible if they contain the same number of parameters 
and if the parameters in corresponding positions match. Two parameters match if one of the 
following is true: 


* They are both value parameters of identical type. 

* They are both variable parameters of identical type. 

* They are both procedural parameters with compatible parameter lists. 

* They are both functional parameters with compatible parameter lists and result-types. 


7.3.6 Implicit parameters 

In the declaration of a method for an object-type, there is an implicit parameter called self. 
The type of self is the type of the object. Sel £’s scope extends over the method 
declaration. The value of se1£ is assigned when the object variable is created. The value is a 
reference to the object whose method component was designated to activate the method. 
The value of self is assigned only when the object is created. No subsequent assignment is 
possible. 
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7.4 Method declarations 


A method declaration describes the implementation of an object’s methods. Methods are 
declared like forward declarations of procedures and functions. The heading appears in the 
declaration of the object (see §3.2.5). The body of the method should appear in the same unit 
as the declaration of the object. 


met hod-declaration 


Inet hod-ident ification] @ 


method-identification 


procedure 


reference-type-identifier 


method identifier 


8.0 Programs and Units 


This section describes how to write the main program and how to declare units in THINK’s 
Lightspeed Pascal. 


8.1 Program Syntax 
A THINK Pascal program has the form of a procedure declaration except for its heading. 


program 


program-heading 


uses-clause 


program-heading 


Wn ee DJ 
(() program-parameters () 


program-parameters 
identifier-list 
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uses-clause 
(uses ) identifier-list @ 


The occurrence of an identifier immediately after the word program declares it as the 
program's identifier. 


The uses-clause identifies all units required by the program. 


8.2 Program-Parameters 


Only the predefined identifiers input and output are allowed as program-parameters. 


8.3 Unit Syntax 


Units provide the means to organize a Pascal program into logically related parts for modular 
construction of programs and libraries. 


unit-heading 


unit 


interface-part implementation-part 


unit-—heading 
unit-identifier 
unit-identifier 
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uses-clause 


ee const-declaration-part ~— 
type-declaration-part 

es var-declaration-part iirc 
procedure-and-function-heading-part 


interface-part 


interface 


implementation-part 


implementation 


. : const-declaration-part — 
Ie type-declaration-part a 
var-declaration-part 


procedure-and-function-declaration-part 


The identifier immediately after the word unit is the unit’s identifier. 


The uses-clause identifies all units required by the unit. 
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procedure-and-function-heading-part 


Q<iaemoay] 
ao 


2 | procedure-heading A tiaot 


function-heading 


The procedures and functions declared in the interface-part must be redeclared in the 
implementation-part. The parameters and function types of these redeclarations may be 
omitted, since they were declared in the interface-part. The procedure and function blocks 
for these routines are included in the implementation-part since they were omitted in the 
interface-part. 


Note: The parameters and functions types can be redeclared in the 
implementation part only if they are identical to the declarations in the 
interface part. 


The scope of the declaration for an interface-part is also the implementation-part which is 
associated with that interface part. 


8.4 Uses-Clause 


The uses-clause is used to control which units are available to the host (other units or the 
main program). Each identifier in the identifier-list of the uses-clause is the name of a unit to 
be made available to the host. All declared entities in the used unit appear as though they are 
declared in the interface part or the main program block which contains the uses-clause. 


8.5 Unit Dependencies 


In order to satisfy the requirements of §2.2.3, a unit must precede any interface-part or 
program that it supplies (see §2.2.6). It is therefore not possible to construct a valid program 
in which two units supply each other. 
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The uses clause in the host must name all units used Girectly or indirectly) by the host. 
Consider the following example: 


program Host; unit Unita; unit UnitB; 

uses interface interface 

Unita; uses const 

begin UnitB b = 3; 

fis implementation implementation 
end. const 

a =b; end. 
end. 


The program Host uses UnitA. UnitA uses UnitB. There is an identifier b defined as a 
constant in the interface of UnitB, but the only reference to b is in the implementation 
part of Unita. In this case, it is not necessary to name UnitB in the uses-clause of Host. 


Now consider the following example: 


program Host; unit UnitA; unit UnitB; 
uses interface interface 
UnitB, Unita; uses const 
begin UnitB; b = 3; 
ats const implementation 
end. a=b; 
implementation end. 
end. 


This example is like the previous one, except that this time the reference to the identifier b is 
in the interface part of Unita. In this case, there is an indirect reference to UnitB and it is 
necessary to name Units in the uses-clause of Host. Note that UnitB must be named 
before Unita. 


9.0 Input/Output 


This section describes the standard built-in I/O procedures and functions of THINK Pascal. 
Standard procedures and functions are predeclared. Since all predeclared entities act as if 
they were declared in a “block” surrounding the program, no conflict arises from a 
declaration that redeclares the same identifier within the program. 


Note: Standard procedures and functions cannot be used as actual 
procedural and functional parameters. 


301 


THINK’s Lightspeed Pascal 


302 


Also, the predeclared file variables input and output do not act as though they are 
declared in a block outside the program. See §9.4. 


This section and §10 use a modified BNF notation, instead of syntax diagrams, to indicate the 
syntax of actual-parameter-lists for standard procedures and functions. 


Example: 
Parameter List: write(f, e; [ , eg, «=, @, 1) 


This represents the syntax of the actual-parameter-list of the standard procedure write, as 
follows: 


° f£, €1, @p, and e, stand for actual-parameters. Notes on the types and 
1&2, n Pi pe: 


interpretations of the parameters accompany the syntax description. 

° The notatione;, €2, .., @n means that any number of actual-parameters can 
appear here, separated by commas. 

¢ Square brackets [ ] indicate parts of the syntax that can be omitted. They do not 
indicate sets. 


Thus the syntax shown here means that the £ parameter is required. Any number of e 
parameters may appear, with separating commas, and there must be at least one e parameter. 


9.1 Introduction to I/O 


A Pascal file variable is any variable whose type is a file-type. There are two classes of files: 
textfiles and non-textfiles. Any file variable declared to be a type identical (see §3.5.1) to 
the standard type text. is a textfile and all others are non-textfiles, The standard type text 
is roughly equivalent to the type packed file of char in thata file of type text may 
be treated as though it were a packed file of char. However, the semantics of the two 
differ somewhat and, in particular, there are certain standard procedures and functions that 
may be applied to textfiles but not to files of type packed file of char. 


A file variable may (but need not) be associated with an external file. The external file may be 
a named collection of information stored on a peripheral device or, depending on the device, 
it may be the peripheral device itself. If a file variable is not associated with an external file or 
device, it is referred to as an anonymous file. 


For a file variable to be used it must be opened. An existing file may be opened with the 
reset and open procedures, and a new file may be created and opened with the rewrite 
and open procedures. Files opened with reset are read-only and files opened with 
rewrite are write-only. However, reset may be applied to a file opened with rewrite, 
which causes the file to become read-only. Likewise, rewrite may be applied to a file 
opened with reset, which causes the file to become write-only. 
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Files opened with open are read/write files, i.e. they allow both reading and writing. 
Reset and rewrite may be applied to files opened with open, but they remain read/write 
files. 


The standard file variables input and output, if present in the program parameter list, are 
opened automatically when program execution begins and should not be opened again with 
reset or rewrite. Input isa read-only file associated with your keyboard and output is 
a write-only file associated with the text window. 


A file is a linear sequence of components, each of which has the component-type of the file. 
Each component has a component-number that is its position in the file relative to the first 
component in the file. The first component of a file is considered to be component zero. 


At any point in time, there is only one component of a file that may be accessed directly 
through the file-buffer denoted by £*. The current file position of f is the component 
number of the component currently accessible through £*. Whenever a file is opened, the 
current file position is set to component zero, i.e. to the beginning of the file. 


Under certain conditions, such as when the current file position is at the end of the file, the 
value of £* is said to be undefined. It is an error to attempt to use the value of £* when the 
value is undefined. Assignment to £* is, however, still possible. 


Note: It is an error to cause the current file position of a file £ to be altered 
while a reference to the file-buffer £* exists. 


Files are normally accessed sequentially. That is, when an I/O operation is completed on a 
file component, the current file position moves to the numerically next file component. Files 
opened with open, however, may also be accessed randomly with the standard procedure 
seek, which may be used to specify that the current file position is to be moved to any 
component number in the file. The function £ilepos (£) may be applied to any file 
variable £ and returns the component number of the current file position. 


9.2 Standard Procedures and Functions for All Files 
The procedures and functions described in this section work on files of any file-type. 


9.2.1 The Reset Procedure 
Opens an existing file for sequential, read-only access or rewinds an open file. 


Parameter List: reset(f [, title ]) 


e  £ isa variable-reference that refers to a variable of file-type. If a title is given, the file 
must not be open. Ifa title is not given, the file must be open. 


* title is an optional expression with a string value. The string should be a valid name 
for a file on a file-structured device, or a name for a non-file-structured device. 
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Reset (f) when f is already open causes f to be “rewound”, i.e. the current file position 
for £ is reset to the beginning of the file. If £ was originally opened with rewrite, £ 
becomes read-only. 


Reset (f,title) finds an existing external file with the name title, and associates f 
with this external file. It is an error if there is no existing external file with that name. 


The following conditions always hold after reset (f£, [title]) is executed: 


* Eof(f) is true if the file is empty. Otherwise, eof (f) is false. 

* The current file position is the first component of the file (component zero) and the 
file buffer variable £* contains the value of that component unless eof (£) is true, 
in which case the value of £* is undefined. 


9.2.2 The Rewrite Procedure 
Creates and opens a new empty file for sequential, write-only access, or rewinds and erases 
an open file. 


Parameter List: rewrite(f [, title ]) 


¢  £ isa variable-reference that refers to a variable of file-type. If a title is given, the file 
must not be already open. 


* title is an optional expression with a string value. The string should be a valid name 
for a file on a file-structured device, or a name for a non-file-structured device. 


Rewrite (f) (with no title) when f is not yet open creates an empty anonymous file for 
writing to. 


Rewrite(f) when f is already open causes f to be “rewound”, i.e. the current file 
position for £ is reset to the beginning of the file and any prior contents of £ ave deleted. If 
£ was originally opened with reset, £ becomes write-only. 


Rewrite(f,title) creates a new external file with the name title, and associates f 
with this external file. If an external file with the name title already exists, it is deleted and 
a new empty file with the same name is created in its place. 


The following conditions always hold after rewrite (f£, [title]) is executed: 


° Eof (f) is true. 
¢ The current file position is component zero, i.e. the first component written to the file 
will become the first component of the file. The value of £* is undefined. 


9.2.3 The Open Procedure 
Opens an existing file or creates and opens a new file for random, read/write access. 
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Parameter List: open(f, title) 
¢ fis a variable-reference that refers to a variable of file-type. £ must not be already open. 


* title is an expression with a string value. The string should be a valid name for a file 
on a file-structured device, or a name for a non-file-structured device. 


Open(f£,title) opens an existing external file with the name title, and associates £ 
with this external file. If an external file with the name title does not already exist, a new 
empty file is created. The file is opened for both reading and writing. 


The following conditions always hold after open (f£, title) is executed: 


¢ Eof(f) is true ifthe file is empty. Otherwise, eof (f) is false. 
¢ The current file position is component zero and the file buffer variable £* contains 
the value of that component (unless eof (£) is true). 


9.2.4 The Close Procedure 
Closes a file. 


Parameter List: close(f) 


e  £ isa variable-reference that refers to a variable of file-type. £ must be open and must 
not be an anonymous file. 


* Close (£) closes f, i.e. the association between f and its external file is broken and the 
file system marks the external file closed. All subsequent references to £ are invalid 
(except to open it again). In particular, the value of £* becomes undefined. 


If a procedure or function block activation that has a file variable £ local to it is exited and f 
is not already closed, £ is closed automatically. If a dynamic variable created with new is, or 
contains, a file variable £ that is still open when the dynamic variable is destroyed with 
dispose, f is closed automatically. If a program terminates with any file still open, the file 
is automatically closed. 


9.2.5 The Eof Function 
Detects the end of a file. 


Result Type: boolean 
Parameter List: eof [ (f) ] 


e £ isa variable-reference that refers to a variable of file-type. If £ is omitted, the function 
is applied to the standard file variable input. The file must be open. 
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Eof (f£) returns true if the current file position is beyond the last component of the file, or 
if the file contains no components; otherwise, eof (f) returns false. Specifically, this 
means the following: 


¢ Aftera get, eof (£) returns true if the previous file position was the last 
component of the file. 

¢ Aftera put, eof (£) returns true if the component written by the put is now the 
last file component. 


Itis always an error todo a get (f£) ifeof(£) istrue.If£ is write-only, eof (f) will 
always be true. 


Note: Whenever eof (f) is true, the value of the file buffer variable £% is 
undefined. 


For some devices, eof may never be true. 
9.2.6 The Get Procedure 


Advances the current file position and reads the next component of a file. 


Parameter List: get (f) 
ef isa variable-reference that refers to a variable of file-type. The file must be open. 


Get (£) advances the current file position to the next file component, and assigns the value 
of this component to £*. If no next component exists, then eof (f£) becomes true, and the 
value of £* becomes undefined. 


9.2.7 The Put Procedure 


Writes the file buffer to the current file position. 


Parameter List: put (f) 


¢ £ isa variable-reference that refers to a variable of file-type. The file must be open and 
the value of £* must not be undefined. 


Put (f) writes the value of £* to f at the current file position and advances the current file 
position to the next file component. If the new file position is beyond the end of the file, 
eof (f) becomes true, and the value of £* becomes undefined. 


Ifeof (£) is true, put (£) effectively appends the value of £* to the end of £ and 
eof (f) remains true. 


9.2.8 The Seek Procedure 
Allows access to an arbitrary file component. 
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Parameter List: seek(f, n) 


e  £ isa variable-reference that refers to a variable of file-type. The file must be open, and 
it must have been opened with open. 


e n is an expression with an integer-type value that specifies a file component number in 
the file. Components in files are numbered from zero. 


Seek(f,n) causes the file component numbered n to become the current file position. The 
value of £* becomes the value of that component unless n is greater than the number of the 
last component of the file, in which case eof (£) becomes true and the value of £% is 
undefined. Thus, seek (f,maxlongint) always sets the current file position to the end of 
file. Seek of a device, such as Printer: or Modem: is not allowed. 


9.2.9 The Filepos Function 
Returns the component number of the current file position. 


Result Type: longint 
Parameter List: filepos (f) 


ef isa variable-reference that refers to a variable of file-type. The file must be open. 


Filepos (f) returns a longint value that is the file component number of the current file 
position. 


9.3 Standard Procedures for Non-Textfiles 


The standard procedures in this section may, in fact, be applied to textfiles. However, their 
interpretation when applied to textfiles is somewhat different and is elaborated in §9.4. 


9.3.1 The Read Procedure for Non-Textfiles 
Reads a file component into a variable. 


Parameter List: read(f, vy [, Vg, =, Vq ]) 


¢  £ isa variable-reference that refers to a variable of file-type. The file must be open. 


e Each v isa variable-reference with a type that the component type of £ must be 
assignment-compatible with. 


If we consider ££ to be the variable referenced by f, then this form of read is considered to 
be equivalent to: 


307 


THINK’s Lightspeed Pascal 


begin 
read (ff, vy); 
read (ff, v2); 


read (ff, v, 
end 


n) 


where read (f, v) isin turn equivalent to: 


begin 
YM eee RSs 
get (ff) 
end 


Note: There is normally a restriction against passing components of packed 
variables as actual variable parameters (§7.3.2). This interpretation of read 

means that each v is not considered an actual variable parameter and may 

be a component of a packed variable. 


To understand why the distinction has to be be made between f and ff above, consider the 
following example: 


var 
a: array[ 1..10 ] of file of integer; 
i, j : integer; 


s 2= 1; 
read(ali]l, i, 4); 


If, say, the value of i that is read is 2, and a[i] is reevaluated for each v, then the value 
read for i will be read from a[1] and the value of } froma[2]. Infact, a[i] is 
evaluated only once before anything is read, and thus all values are read from a[1] . ££ is 
the result of this one-time evaluation. This ££ notation will be used again in subsequent 
sections. 


9.3.2 The Write Procedure for Non-Textfiles 
Writes a file component from a variable. 


Parameter List: write(f, e,; [, e9, ., @, 1) 


° f isa variable-reference that refers to a variable of file-type. The file must be open. 
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e ache isan expression with a type that must be assignment-compatible with the 
component type of £. 


If we consider ££ to be the variable referenced by f, then this form of write is considered 
to be equivalent to: 


begin 
write (ff, e,); 
write (ff, e9); 


write (ff, e 
end 


where write(f, e) is in turn equivalent to: 


begin 
£i* s= e; 
put (ff) 
end 


9.4 Standard Procedures and Functions for Textfiles 

This section describes input and output using file variables of the standard type text. As 
previously noted, in Pascal the type text is distinct from packed file of char.A 
textfile is still considered to be a sequence of character components (i.e. is it still a packed 
file of char). However, it is additionally considered to be a sequence of lines, where 
each line is terminated by an end-of-line character. 


All of the standard procedures and functions in §9.2 may still be applied to a textfile as 
though it were a packed file of char. However, there are additional procedures and 
functions you can use with textfiles but not other files. 


Note: When the value of the file component at the current file position of a 
file £ is an end-of-line character, it appears in the file buffer £* as a space 
character. 


In particular, there are special forms of read and write that allow you to read and write 
values that are not of type char and will translate them to and from their character 
representation. For example, read(f£,i) where i is an integer variable will reada 
sequence of digits (a digit being one of the characters '0' through ' 9"), interpret that 
sequence as an integer-type value, and store itin i. 


As noted previously there are two standard textfile variables, input and output. The 
standard file variable input is a read-only file associated with your keyboard. If input 
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appears in the program parameter list, then the input file is opened automatically when 
program execution begins as though a reset were performed for it. The standard file 
variable output is a write-only file associated with the Text window. If output appears in 
the program parameter list, then the output file is opened automatically when program 
execution begins as though a rewrite were performed for it. 


All of the standard procedures and functions in this section need not have a file variable 
explicitly given as a parameter (in addition to eof, as described in §9.2.5). In these cases, 
input or output will be assumed by default, depending on whether the procedure or 
function is input-oriented or output-oriented. 


9.4.1 The Read Procedure for Textfiles 
Reads one or more values from a textfile into one or more program variables. 


Parameter List: read([ f£, ] vy [, Var =, Vy 1) 


¢ £ (if given) is a variable-reference that refers to a variable of type text. The file must be 
open. If £ is omitted, it is assumed to be the standard text file input. 


¢ Each v isa variable-reference that refers to a variable of one of the following types: 


° Char ora subrange of char. 

e An integer-type: integer (ora subrange) or longint. 

e Areal-type: real, double, extended, or computational. 
e An enumerated-type (including boolean) ora subrange. 

¢ A string-type. 


Read(f, vy, .., Vp) is equivalent to: 


begin 
read(ff, v,); 
read(ff, vo); 


read(ff, v. 
end 


int 


9.4.1.1 Read with a Char-Type Variable 
This is considered equivalent to: 


begin 
ess tee 
get (ff) 
end 
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Remember that if the current file position is over an end-of-line character, ££* contains a 
space character. 


9.4.1.2 Read with an Integer-Type Variable 

Iff£ is of type text and v is of an integer-type, then read (f,v) implies the reading from f£ 
of a sequence of characters that form a signed whole number according to the syntax of §1.4 
(except that hexadecimal notation is not allowed). If the value read is assignment-compatible 
with the type of v, then the value is assigned to the variable v; otherwise, it is an error. 


In reading the sequence of characters, blanks and end-of-line characters preceding the first 
digit or the sign are skipped. Reading ceases as soon as a character is reached that, together 
with the characters already read, does not form part of a signed whole number, or as soon as 
eof(f) becomes true. 


It is an error if a signed whole number is not found after skipping any preceding blanks and 
end-of-line characters. 


The following things are true immediately after read (£,v) when v is of an integer-type: 


¢ The current file position will be over the character following the last character in the 
numeric string, unless the last character in the string was the last character in the file. 

¢ Eof(f) will return true if the last character in the numeric string was the last 
character in the file. 

¢ Eoln(£) will return true if the last character in the numeric string was the last 


character on the line. 


9.4.1.3 Read with a Real-Type Variable 

If£ is of type text and v is ofa real-type, then read(f,v) implies the reading from £ of 
a sequence of characters that represents a signed-number according to the syntax of §1.4 
(again, except for hexadecimal notation). If the value read is assignment-compatible with the 
type of v, then the value is assigned to the variable v; otherwise, it is an error. 


In reading the sequence of characters, blanks and end-of-line characters preceding the first 
digit or the sign are skipped. Reading ceases as soon as a character is reached that, together 
with the characters already read, does not form a valid signed-number. 


It is an error ifa valid signed-number is not found after skipping any preceding blanks and 
end-of-line characters. 


Immediately after read (f£, v) , where v is a real-type variable, the following conditions are 
true: 


¢ The current file position will be over the character following the last character in the 
numeric string, unless the last character in the string was the last character in the file. 
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° Eof(£) willreturn true if the last character in the numeric string was the last 
character in the file. 

¢ Eoln(f) will return true if the last character in the numeric string was the last 
character on the line. 


9.4.1.4 Read with a String-Type Variable 

If£ is of type text and v is ofa string-type, then read (f£,v) implies the reading from f of 
a sequence of characters up to but not including the next end-of-line character, or until the 
end of the file. The resulting character-string is assigned to the variable v. It is an error if the 
number of characters read exceeds the size attribute of v. 


Note: Read with a string variable does not skip to the next line after 
reading, and the end-of-line character is left waiting in the file buffer. For 
this reason, you cannot use successive read calls to read a sequence of 
strings, as they will never get past the first line — after the first read, each 
subsequent read will see the end-of-line and will read a zero-length string. 
Instead, use readin to read string values (see §9.4.2). Readin skips to the 
beginning of the next line after reading. 


The following things are true immediately after read (£,v) when v is of a string-type: 


* The current file position will be over the character following the last character in the 
string, unless the last character in the string was the last character in the file. 

° Eof (f) will return true if the last character in the string was the last character in the 
file, 

* Eoln(f) will return true unless eof (f£) is true. 


9.4.1.5 Read with an Enumerated-Type Variable 

If£ is of type text andv is of an enumerated type, then read(f,v) implies the reading 
from £ ofa sequence of characters that form an identifier according to the syntax of §1.2. If 
the identifier read is identical (ignoring the case of letters) to an enumerated constant of the 
enumerated type of v, the value of the enumerated constant is assigned to v; otherwise, it is 
an error. 


In reading the sequence of characters, blanks and end-of-line characters preceding the first 
letter of.the identifier are skipped. Reading ceases as soon as a character is reached that, 
together with the characters already read, does not form part of an identifier, or as soon as 
eof (£) becomes true. 


Itis an error if an identifier is not found after skipping any preceding blanks and end-of-line 
characters. 


Iff is of type text, the following things are true immediately after read (£,v) when v is 
an enumerated-type variable: 
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e The current file position will be over the character following the last character in the 
identifier, unless the last character in the string was the last character in the file. 

© Eof(f) will return true if the last character in the identifier was the last character 
in the file. 

* Eoln(£) will return true if the last character in the identifier was the last character 
on the line. 


9.4.2 The ReadIn Procedure 
The readin procedure is an extension of read for textfiles. Essentially it does the same 
thing as read, and then skips to the beginning of the next line in the input file. 


Parameter List: same as for read, except: 


¢ A readln call with no input variables is allowed: 
readin (sourcefile) 


e The parameter-list can be omitted altogether. 


If the first parameter does not specify a file variable, or if the parameter-list is omitted, the 
procedure reads from the standard file input. 


Readln (£), with no input-variables, causes the current file position to advance to the 
beginning of the next line (if there is one, else to the end of the file), i.e.: 


begin 
while not eof(ff) and not eoln(ff) do 
get (ff); 
if not eof(ff) then 
get (ff) 
end 


Readln(f£, vy, ., Vy) is equivalent to: 


begin 
read(ff ,vy, wr Vy)i 


readin (ff) 
end 


The following conditions are true immediately after readln (f, v) , regardless of the type of 
Vv: 


* Eof(f£) will return true if the line read was the last line in the file. 
* Eoln(£) will return false unless the line following the line read is empty. 
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9.4.3 The Write Procedure for Textfiles 
Writes one or more values to a text file. 


Parameter List: write([ £, ] py [, Po, «, Pp 1) 


e £ (if given) is a variable-reference that refers to a variable of type text. The file must be 
open. If £ is omitted, the procedure writes to the standard file output. 


° Py, «, Py are write-parameters. Each write-parameter includes an output 
expression, whose value is to be written to the file. As explained below, a write- 
parameter may also contain the specifications of a field-width and a number of decimal 
places. Each output expression must have a result of char-type, an integer-type, a real- 
type, a string-type, a packed-string-type, or an enumerated-type. At least one write- 
parameter must be present. 


Write(f, Py, .. Py) is equivalentto: 


begin 
write (ff, pi); 


write(ff, pnp) 
end 


9.4.3.1 Write-Parameters 
Each write-parameter has the form 


OutExpr [ : MinWidth [ : DecPlaces ] ] 


where Out Expr is an output expression. MinWidth and DecPlaces are expressions with 
integer-type values. 


MinWidth specifies the minimum field width. MinWidth must be greater than zero. 
Exactly MinWidth characters are written (using leading spaces if necessary), except when 
OutExpr has a value that must be represented in more than MinWidth characters; in this 
case, enough characters are written to represent the value of Out Expr. Likewise, if 
MinWidth is omitted, then enough characters as necessary are written to represent the value 
of OutExpr. 


DecPlaces specifies the number of decimal places in a fixed-point representation of a 
real value. It can be specified only if OutExpr has a real-type value, and if MinWidth is 
also specified. If specified, it must be greater than zero. If DecP laces is not specified, a 
floating-point representation is written. 
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9.4.3.2 Write with a Char-Type Value 
If MinWidth is omitted, the character value of Out Expr is written on the file £. Otherwise, 
MinWidth-1 spaces followed by the character value of Out Expr is written. 


9.4.3.3 Write with a String-Type Value 

Assuming the string value of OutExpr has a length L, if L<MinWidth, the string value is 
written on the file £ preceded by MinWidth-L spaces. If L>MinWidth, the first MinWidth 
characters of the string are written. If L=MinWidth, or ifMinWidth is omitted, the entire 
string value is written on the file. 


9.4.3.4 Write with an Integer-Type Value 

If Out Expr has an integer-type value, its decimal (base 10) representation is written on the 
file £. Assume that OutDigits is a string-type value that contains the decimal 
representation of abs (OutExpr) with no leading zeros unless the value of OutExpr=0, in 
which case OutDigits contains the single character '0'. IfMinWidth is omitted from the 
write-parameter, then it is assumed to be zero. Thus, the representation of Out Expr is 
written to £ as if by the algorithm: 


begin 
if MinWidth>=length (OutDigits)+1 then 
write(ff, ' ' : MinWidth-length (OutDigits) -2); 
if OutExpr<0 then 
write (ff, '-') 
else if MinWidth>=length(OutDigits)+1 then 
write(ff, ' '); 
write(ff, OutDigits) 
end 


9.4.3.5 Write with a Real-Type Value 

If OutExpr has a real-type value, its decimal representation is written on the file £. This 
representation depends on the presence or absence of and, if present, the value of 
DecPlaces. 


If DecP laces is present, a fixed-point representation is written. Assume that IntDigits 
is a string-type value that contains the decimal representation of trunc (abs (OutExpr) ) 
with no leading zeroes unless the value of OutExpr=0, in which case IntDigits contains 
the single character '0'. Assume that FracDigits is a string-type value that contains the 
decimal representation of 


round((abs(OutExpr) - trunc(abs(OutExpr))) * 10DecPlaces) 


with enough leading zeroes to make length (FracDigits) =DecPlaces. Thus, the 
fixed-point representation is written to £ as if by the algorithm: 
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begin 
if MinWidth>=length (IntDigits) t+length(FracDigits)+2 then 
WRite (fe, * I 2 MinWidth-TotalDigits-3) ; 
if OutExpr<0 then 
write (ff, '-') 
else if MinWidth>=length (IntDigits)+length(FracDigits)+2 then 
write(ff, ' '); 
write(ff, IntDigits, '.', FracDigits) 
end 


If DecPlaces is not specified, a floating-point representation is written. If MinWidth is 
omitted from the write-parameter, then it is assumed to be 10. Assume that abs (Out Expr) 
has a representation in the floating-point notation of the form: 


m.n x 10® 


where 0<ms<9 unless OutExpr=0, in which case m=n=e=0. Assume that IntDigit isa 
string-type value that contains the decimal representation of m (a single digit). Assume that 
FracDigits is a string-type value that contains the first MinWidth-9 digits of the decimal 
representation of n rounded, and with leading zeros retained and trailing zeros added if 
necessary. Assume that ExpDigits is a string-type value that contains the decimal 
representation of abs (e) with enough leading zeros to make length (ExpDigits) =4, 
Also assume that NegExp has the value true if e<0, and otherwise the value false. Thus, 
the floating-point representation is written to £ as if by the algorithm: 


begin 
if OutExpr<0 then 
write(ff, '-') 
else 
write (ff, ' '); 
write(ff, IntDigit, '.', FracDigits, 'E'); 
if NegExp then 
write(ff, '-') 
else 
write(ff, '+'); 
write(ff, ExpDigits) 
end 


9.4.3.6 Write with a Packed-String-Type Value 
If Out Expr is of a packed-string-type, the effect is the same as writing a string whose length 
is the number of components in the type. 


9.4.3.7 Write with an Enumerated-Type Value 
If the value of Out Expr is of an enumerated type, the string representation of the 
enumerated constant identifier corresponding to the value is written on the file £. If the 
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length of this string representation is L and L<MinWidth, then MinWidth-L spaces are 
written out before the string. In any case the entire string is always written, even if 
L>MinWidth 


9.4.4 The Writeln Procedure 
The writeln procedure is an extension of write for textfiles. Essentially it does the same 
thing as write, and then writes an end-of-line character to the output file (ending the line). 


Parameter List: sameasfor write, except: 


¢ Awriteln call with no write-parameters is allowed: 
writeln(outputfile) 


¢ The parameter-list can be omitted altogether. 


If the first parameter does not specify a file variable, or if the parameter-list is omitted, the 
procedure writes to the standard file output. 


Writeln(f£) writes an end-of-line character to the file f. 


Writeln(f, py, .., Py) is equivalent to: 


begin 
write(ff, Py, «. Pp)i 
writeln (ff) 

end 


The following are true immediately after writeln (f£,v), regardless of the type of v: 


© Eof (f) will return true if the last character written became the last character in the 
file. If £ is write-only, then eof (£) will necessarily be true. 

* Eoln(f) will return false unless the character following the last character written 
is an end-of-line character. 


9.4.5 The Eoln Function 


Result Type: boolean 
Parameter List: eoln [ (f) ] 


e fis avariable-reference that refers to a variable of type text. The file must be open. If £ 
is omitted, the function is applied to the standard file input. 


Eoln(f) returns true if the character at the current file position is an end-of- line character. 
Itis an error to call eoln(f) if f is a non-textfile, if £ is write-only, or if eof (£) is true. 
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Note: Every line in a file is expected to be terminated by an end-of-line 
character. This may not actually be the case. The last character in a file may 
not be an end-of-line character as it should. If a file £ is read-only (opened 
with reset) then, upon reaching the end of the file, if the last character was 
not an end-of-line character, £* becomes a space character, eoln (f) 
becomes true, and eof (£) remains false. The next attempt to reada 
character will then cause eof (£) to become true. This will only happen if 
the file is read-only and not if it is read/write. 


9.4.6 The Page Procedure 


Parameter List: page [ (f) J 
¢ fis a variable-reference that refers to a variable of type text. The file must be open. 


If £ is omitted, the standard textfile output is assumed. Page (£) causes a skip to the top of 
a new page when f is printed or displayed. If £ is write-only, and if the last character in £ is 
not an end-of-line character, then one is inserted before the page is done. 


9.4.7 Lazy 1/O 


Consider this small program: 


program count (input, output); 
var 
Ss: string; 
ch: char; 
begin 
write('Type a line of characters -- '); 
readln(s) ; 
writeln('You typed ', length(s), ' characters'); 
end. 


If you take all the parts of this section literally, there are two problems with this program: 


¢ Because reset (which is done implicitly for input when the program starts) causes the 
first character of input to appear in input”, the program will hang waiting for input 
from the keyboard before the write statement is executed. This means the prompt the 
program is supposed to give you for input will not appear until after you type a 
character. 


° Having typed a line of characters followed by the Return key (the “end-of-line key” so to 
speak), readin causes the first character of the line following the one just read to 
appear in input%. This means that the writeln following the read1n will not be 
executed until you type another character following the return. 
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This behavior has been the bane of Pascal programmers since the language was created. This 
idiosyncrasy exists partly because Pascal was originally designed to run on batch systems — 
back in the days when interactive systems were rare. 


On batch systems, input was expected to be associated with a previously prepared input 
file (typically a deck of punched cards) and output was expected to be associated with a 
file where the results of your program would appear for your inspection after its execution 
was complete (typically a line printer listing). 


Although, when the ANSI Pascal Standard was being drafted, many subtle changes were 
made to the Pascal language, this problem was never completely resolved. So many 
programs had already been written that depended on this behavior when doing I/O. To 
change the language in any significant way would have made these programs invalid. 
Instead, the standard is worded in such a way that it is possible to get around this problem. 


For instance, when the standard specifies that, after reset (£) , £* contains the first 
component of the file, it does so in a way that allows £* to remain undefined until its value 
is needed. Thus, in the above program, it’s not strictly necessary to read the first character 
from the keyboard as soon as execution begins; it suffices to do so when the readln needs 
that character. Likewise, after readln processes the end-of-line character (the Return key), it 
is not necessary to then read another character from the keyboard. It is in fact never 
necessary because the program does not reference input again. 


Interpreting the standard’s semantics in this way is popularly known as Lazy I/O, and is the 
only technique that allows interactive I/O in Pascal while preserving the standard’s I/O 
semantics. Other techniques exist, but they cause I/O operations to behave differently 
depending on whether you have specified that the I/O is to be done interactively or not. 
These other techniques make it difficult to write a program that runs the same when its input 
comes from a file as it does when input comes from a keyboard. 


The Lazy I/O technique involves separating the operations of advancing the current file 
position and doing input from the file by deferring the actual input of data from a file until 
absolutely necessary. Conditions that make input from a file £ necessary include: 


e Areference to £* other than to assign it a value or to pass it as an actual variable 
parameter. 

e Acallto eof (f) . In this case, input may be necessary because it is not (necessarily) 
possible to know whether the end of the file has been reached without trying to read 
beyond it. 

e. Acall to coln(£) . In this case, input may be necessary to get another character and 
see if it is an end-of-line character. 

e¢ Acallto get (£) . In this case, input will only be necessary if prior to the call to get 
there was deferred input that was never actually done. If so, the original deferred 
input will be performed, but the input implied by the get will in turn be deferred. 
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¢ Acall to read or readin from f. Here, the input necessary to do the read or 
read1n will be performed, but the input of the component following the last 
component read will be deferred. 


Although Lazy I/O makes it possible to write interactive programs without much difficulty, 
you should nevertheless be aware of the conditions described above to avoid peculiar 
situations that may cause your program to hang waiting for input unexpectedly. For instance: 


program process_lines(input, output); 
var 
S : string; 


begin 
repeat 
write('>'); 
readin(s); 


until eoln 
end. 


This program might be intended to read and process lines, prompting each line with the '>*' 
character, until an empty line is entered. An empty line is an end-of-line character 
immediately following the end of the previous line. The program reads a line and tests to see 
if an end-of-line immediately follows. The problem is that the program, after prompting for 
and reading the first line, will stop as a result of the eo1n and wait for another character to be 
typed before issuing another prompt. A better way to write this program, one that avoids this 
problem, might be: 


program process _lines(input, output) ; 
var 
Ss: string; 
empty : boolean; 


begin 
empty := false; ~- 
repeat 
write('>"'); 
if eoln then 
empty := true 
else 
begin 
readin (s); 
end 
until empty 
end. 
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or even better: 


program process _lines(input, output); 
var 
Ss : string; 
begin 
repeat 
write ('>"'); 
readin(s); 


until length(s) = 0 
end. 


9.5 Devices on the Macintosh 


On the Macintosh, there are basically three devices to be concerned about: disk drives, a 
printer, and a modem. 


The disk drives are never addressed directly. Rather, you address the disks themselves by 
name. Each disk is referred to as a volume and the disk’s name is its volume name, For disk 
files, the title parameter for reset, rewrite, and open (see §§9.2.1 through 9.2.3) 
consists of a file name optionally preceded by a volume name and a colon, e.g.: 


MyVolume:MyFile 


To learn more about volumes and files, see Inside Macintosh II, Chapter 4, “The File 
Manager” and Inside Macintosh IV, Chapter 19, “The File Manager.” 


For the printer and modem, the title parameter for reset, rewrite, and open consists of 
the device name followed by a colon: 


Printer: 
Modem: 


The device name for the printer is simply printer: . Likewise the device name for the 
modem is modem: . 


Since the printer is a write-only device, you can only use ‘printer: ' as the title parameter 
for rewrite. It is an error to give ‘printer: ' as the title parameter for reset or open. 


e A file variable opened with 'modem: ' as the title parameter reads from and writes to the 
modem at 300 baud. 
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e Itis an error to open a file variable with 'printer:' or 'modem: ' as the title 
parameter if it is not of type text. 


¢ For the printer and the modem to work properly, they must be connected to their proper 
sockets in the back of the Macintosh. See the Macintosh user's manual for details. 


9.6 Error Handling Routines 

Most of the time, THINK Pascal reports I/O errors with a dialog box. When the dialog box 
appears, it doesn’t give you an opportunity to handle the error in your program. The routines 
described in this section, let you turn off THINK Pascal’s I/O error checking so you can do it 
yourself, 


9.6.1 IOCheck 
Enables and disables runtime checking of I/O errors. 


Parameter List: IOCheck (bool) 


¢ Bool is a boolean value. If bool is true, THINK Pascal reports dynamic errors. If 
bool is false, you can check the results of input/output operations with the 
IOResult function, 


9.6.2 1OResult 
Returns result of last of I/O routine. 


Return type: integer 
Parameter List: IOResult 


TOResult returns the result of the last I/O operation. If the value is negative, it is a Macintosh 
error. The meanings of positve values are: 


0— no error 
15— can’t CLOSE an anonymous file 
16— file is not opened for writing 
17— file is not opened for reading 
18 — file is not opened for random access 
19— end of file during read 
20— file is not open 
21—file is nota disk file 
22— component in seek is < 0 
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23— file is already open 

24— bad device type for open, rewrite, or reset 
25— portis in use by AppleTalk 

26 — illegal signed number in read 

27 — string too long in read or write 

28 — illegal enum value in read 

29 — illegal floating point value in read 


10.0 Standard Procedures and Functions 


This section describes all the standard (built-in) procedures and functions in THINK Pascal, 
except for the I/O procedures and functions described in §9, and the Macintosh Toolbox 
procedures and functions described in Inside Macintosh. 


Standard procedures and functions are predeclared. Since all predeclared entities act as if 
they were declared in a block surrounding the program, no conflict arises from a declaration 
that redeclares the same identifier within the program. 


Note: You cannot use standard procedures and functions as actual 
procedural and functional parameters. 


This section uses a modified BNF notation, instead of syntax diagrams, to indicate the syntax 
of actual-parameter-lists for standard procedures and functions. The notation is explained at 
the beginning of §9. 


10.1 Dynamic Allocation Procedures 

The procedure new creates dynamic variables that your program uses. Dynamic variables are 
variables that can be accessed only through pointer variables, and they are created by 
allocating a region of memory from a portion of free memory called the heap. The address of 
the allocated region is the pointer value that is used to access the dynamic variable. The 
dispose procedure is used to destroy dynamic variables created with new, in the process 
returning that variable’s region of memory to the heap for reuse. 


10.1.1 The New Procedure 
Creates a new dynamic variable and sets a pointer variable to point to it. 
Creates a new object and sets a reference variable to reference it. 


Parameter List: new(p [, Cy, Cg, «, Cy ]) 


e pis a variable-reference that refers to a variable of any pointer-type. This is a variable 
parameter. 
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e Each c (if given) is a constant. If the base-type of p is a record-type with variants, then 
each c may be a constant corresponding to a case-constant of a variant of a variant-part 
(see below). Variants are not allowed for reference variables. 


Or: 
e psa variable-reference that refers to a variable of reference-type. 


New (p) creates a new variable of the base-type of p, and makes p point to it. The variable 
can be referenced as p*. 


It is an error if the heap does not contain enough free space to create the new variable. 


Normally, if the base-type of p is a record-type with a variant-part, new (p) allocates enough 
memory to the variable to accommodate the largest variant. However, by supplying a 
constant c that is a case-constant of one of the variants of the variant-part, only the amount of 
memory necessary to accommodate that particular variant is allocated to the variable. 


If the record variant itself contains a variant-part, then a case-constant c may be given to 
select a particular variant of that variant-part, and so on. Each c in the parameter list must be 
given in the order of the nesting of the variants, one for each level of nesting. 


If the variant selected by c,, (the last c given in the parameter list) has itself a variant-part, 


then enough memory is allocated to the variable to accommodate the largest variant of that 
variant-part. 


Warning: When a record variable is dynamically allocated with case- 
constants as shown above, you must not make assignments to any fields of 
variants that are not selected by the case-constants. Also, you must not 
assign an entire record variable to this record or use the entire record in an 
expression or as an actual parameter. 


If p is a reference variable, new creates an object whose type corresponds to p’s reference 
type and sets p to reference it. 


10.1.2 The Dispose Procedure 
Destroys a dynamic variable or reference variable. 


Parameter List: dispose(p [, Cy, Cg, m=, Cp ]) 


« pis a variable-reference that refers to a pointer-variable. It must be a pointer that was 
previously assigned by the new procedure or was assigned a meaningful value by an 
assignment statement. It is an error to attempt to dispose of a pointer variable that is 
currently being accessed, or whose value is undefined or is nil 
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e Each c (if given) is a constant. If the base-type of p is a record-type with variants, then 
each c may be a constant corresponding to a case-constant of a variant of a variant-part 
(see 10.1.1 above). 


Or: 
* pisa variable reference that refers to a variable of reference-type. 


Dispose (p) destroys the variable referenced by p and returns its memory region to the 
heap. The value of p then becomes undefined and it is an error to subsequently make 
reference to p*. 


If the dynamic variable pointed to by p was created by new with a list of case-constants, then 
the same list of case-constants (in the same order) must be given to dispose. 


10.1.3 HeapCheck Procedure 


Enables and disables runtime checking of dynamic memory errors. 


Parameter List: HeapCheck (bool) 


* Bool is a boolean value. If bool is true, THINK Pascal reports dynamic errors. If 
bool is false, you can check the results of dynamic memory allocations with the 
HeapResulz function. 


10.1.4 HeapResult Function 
Returns result of the last of dynamic memory allocation routine. 


Return type: integer 
Parameter List: HeapResult 


HeapResult returns the result of the last heap operation. If the value is negative, it is a 
Macintosh error. The meanings of positve values are: 


O— no error 
11— attempt to DISPOSE a nil pointer 


10.2 Transfer Procedures and Functions 
10.2.1 The Pack Procedure 
Transfers the contents of an array toa packed array. 


Parameter List: pack(a, i, z) 
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* ais a variable of an array-type and z is a variable of a packed-array-type whose 
component-type is the same as the component-type of a. i is an expression whose value 
is assignment-compatible with the index-type of a. 


Pack (a,i,z) copies the components of a to z starting at the it® component of a and 
continues until all components of z have been copied to. 


If j is a variable with the same type as the index-type of z, if k is a variable with the same 
type as the index-type of a, and if u and v are the lowest and highest possible values of the 
index-type of z, then pack (a, i, z) is equivalent to: 


begin 
k := 1; 
for j := u to v do 
begin 
z(j] == alk); 
if j <> v then 
k := succ(k) 
end 
end 


Itis an error if the number of components comprising the it through last components of a 
is less than the number of components of z. It is an error if any component of a accessed is 
undefined. 

10.2.2 The Unpack Procedure 


Transfers the contents of apacked array to an array. 


Parameter List: unpack(z, a, i) 


¢  zisa variable of a packed array-type and a is a variable of an array-type whose 
component-type is the same as the component-type of z. i is an expression whose value 
is assignment-compatible with the index-type of a. 


Unpack (z,a,i) copies the components of z to a starting at the it? component of a and 
continues until all components of z have been copied. 


If is a variable with the same type as the index-type of z, if k is a variable with the same 


type as the index-type of a, and if u and v are the lowest and highest possible values of the 
index-type of z, then unpack (z,a,i) is equivalent to: 
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begin 
k r= 
for j := u to v do 
begin 
alk] := z[3l]; 
if j <> v then 
k := succ(k) 
end 
end 


It is an error if the number of components comprising the it® through last components of a 
is less than the number of components of z. It is an error if any component of z is undefined. 


10.2.3 The Trunc Function 


Converts a real-type value to a longint value. 


Result Type: longint 
Parameter List: trunc (x) 


¢ xis an expression with a value of a real-type. 


Trunc (x) returns a longint result that is the value of x rounded to the nearest whole 
number that is between 0 and x inclusive. It is an error if the result of this rounding is outside 
the range -maxlongint-1..maxlongint. 


10.2.4 The Round Function 


Converts a real-type value to a longint value. 


Result Type: longint 
Parameter List: round (x) 


¢ xis an expression with a value of a real-type. 


Round (x) returns a longint result that is the value of x rounded to the nearest whole 
number. If x is exactly halfway between two whole numbers, the result is the whole number 
with the greatest absolute magnitude. It is an error if the result of this rounding is outside the 
range -maxlongint..maxlongint. 


10.2.5 The Ord4 Function 
Converts an ordinal-type or pointer-type value toa longint value. 


Result Type: longint 
Parameter List: ord4 (x) 


e xis an expression with a value of ordinal-type or pointer-type. 
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Ord4 (x) returns the ordinal value of x. 
If x is of a pointer-type, the result is the address of the dynamic variable pointed to by x. 


If x is of an ordinal-type, the result is the ordinality of x (see §3.1.1), represented as a 
longint. 


10.2.6 The Pointer Function 
Converts an integer-type value to a generic pointer-type value. 


Result Type: a generic pointer which matches any pointer 
Parameter List: pointer (x) 


* xis an expression with a value of integer-type. 


Pointer (x) returns a pointer value that points to whatever is at the address x as though it 
were a dynamic variable created at that address. This pointer is of the same type as nil in 
that it is assignment-compatible with any pointer-type. 


As a convenience, pointer may be also applied to an expression of any pointer-type, 
effectively making that expression assignment-compatible with any (other) pointer-type. 


10.3 Arithmetic Functions 


In general, any extended real-type result returned by an arithmetic function is an 
approximation. There is one exception to this: the result of the abs function is exact. 


10.3.1 The Odd Function 
Tests whether an integer-type value is odd. 


Result Type: boolean 
Parameter List: odd(x) 


* x is an expression with a value of an integer-type. 


Odd (x) returns true if x is odd, i.e. not divisible by 2 without a remainder. If x is even it 
returns false. 


10.3.2 The Abs Function 
Returns the absolute value of a numeric value. 


Result Type: integer, longint, or extended. 
Parameter List: abs (x) 


* x is an expression with a value of an integer-type or a real-type. 
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Abs (x) returns the absolute value of x; i.e. if x is negative, -x is returned; otherwise x is 
returned. If x is of a real-type, the result type is extended. If x is of type longint, the 
result type is Longint. Otherwise, the result type is integer. 


10.3.3 The Sqr Function 
Returns the square of a numeric value. 


Result Type: integer, longint, or extended. 
Parameter List: sqr(x) 


e xis an expression with a value of an integer-type or a real-type. 
Sqr (x) returns the square of x, i.e. x*x. 


Itis an error if the result is not within the range of values representable by the result-type (see 
§3.1). 


10.3.4 The Sqrt Function 


Returns the square root of a numeric value. 


Result Type: extended 
Parameter List: sqrt (x) 


* xis an expression with a value of an integer-type or real-type. It is an error if x<0. 


Sqrt (x) returns the positive square root of x, i.e. the positive value y such that y*y=x. It 
is an error if the result is a value too small to be represented by the real-type ext ended (sce 
§3.1.2). 


10.3.5 The Sin Function 
Returns the sine of a numeric value. 


Result Type: extended 
Parameter List: sin(x) 


e x is an expression with a value of an integer-type or real-type. This value is assumed to 
represent an angle in radians. 


Sin (x) returns the trigonometric sine of x. 


10.3.6 The Cos Function 
Returns the cosine of a numeric value. 
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Result Type: extended 
Parameter List: cos (x) 


e xis an expression with a value of an integer-type or real-type. This value is assumed to 
represent an angle in radians. 


Cos (x) returns the trigonometric cosine of x. 
10.3.7 The Exp Function 


Returns the exponential of a numeric value. 


Result Type: extended 
Parameter List: exp (x) 


e xis an expression with a value of an integer-type or real-type. 


Exp (x) returns the value of e*, where é¢ is the base of the natural logarithms. It is an error if 
the result cannot be represented with the real-type ext ended (see §3.1.2). 


10.3.8 The Ln Function 
Returns the natural logarithm of a numeric value. 


Result Type: extended 
Parameter List: 1n(x) 


¢ xis an expression with a value of an integer-type or real-type. It is an error if x<0. 
Ln (x) returns the natural logarithm (log,) of x. 


10.3.9 The Arctan Function 
Returns the arctangent of a numeric value. 


Result Type: extended 
Parameter List: arctan (x) 


e x is an expression with a value of an integer-type or real-type. It is an error if x<0. 
Arctan (x) returns the principal value, in radians, of the arctangent of x. 


10.4 Ordinal Functions 
10.4.1 The Ord Function 
Returns the ordinal number of an ordinal-type or pointer-type value. 
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Result Type: integer or longint 
Parameter List: ord(x) 


e xis an expression with a value of ordinal-type or pointer-type. 


If x is of pointer-type, the result is the longint address of the dynamic variable pointed to 
by x. 


If x is of an ordinal-type, the result type is the ordinality of x (see §3.1.1). If x is of type 
longint, the resulttype is longint. Otherwise, the result type is integer. 


10.4.2 The Chr Function 
Returns the char value corresponding to a whole-number value. 


Result Type: char 
Parameter List: chr(x) 


¢ x is an expression with an integer-type value that must be in the range 0..255. 
Chr (x) returns the char value whose ordinal number is x. 


For any char value ch, the following is always true: 


chr(ord(ch)) = ch 


10.4.3 The Succ Function 
Returns the successor of a value of ordinal-type. 


Result Type: same as parameter 
Parameter List: succ (x) 


¢ x is an expression with a value of ordinal-type. 
Succ (x) returns the successor of x. 


It is an error if x is the last value in the type of x, i.e. it has no successor. Otherwise 


ord (succ (x) )=ord (x) +1 


10.4.4 The Pred Function 
Returns the predecessor of a value of ordinal-type. 


Result Type: same as parameter 
Parameter List: pred (x) 
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* x is an expression with a value of ordinal-type. 
Pred (x) returns the predecessor of x. 


Itis an error if x is the first value in the type of x, i.e. it has no predecessor. Otherwise, 


ord (pred (x) ) =ord (x) -1 


10.5 String Procedures and Functions 
10.5.1 The Length Function 
Returns the current length of a value of string-type. 


Result Type: integer 
Parameter List: length(str) 


* str is an expression with a value of a string-type. 


Length (str) returns the current length attribute of st r (see §3.3). 


10.5.2 The Pos Function 
Searches a string for the first occurrence of a specified substring. 


Result Type: integer 
Parameter List: pos(substr, str) 


* substr is an expression with a value of a string-type. 
* str is an expression with a value of a string-type. 


Pos(substr, str) searches for substr within str, and returns an integer value that 
is the index of the first character of subst r within str. 


If substr is not found, pos(substr, str) returns zero. 


10.5.3 The Concat Function 
Takes a sequence of strings and concatenates them. 


Result Type: string-type 
Parameter List: concat(str, [, str2, .. str, ]) 


¢ Each parameter is an expression with a value of string-type. Any practical number of 
Parameters may be passed. 
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Concat (strj, .., Stx,) concatenates all the parameters in the order in which they are 


written, and returns the concatenated string. Note that the number of characters in the result 
cannot exceed 255. 


10.5.4 The Copy Function 


Returns a substring of specified length, taken from a specified position within a string. 


Result Type: string-type 
Parameter List: copy(source, index, count) 


® source is an expression with a value of a string-type. 
* index is an expression with an integer-type value. 
* count is an expression with an integer-type value. 


Copy (source, index, count) returns a string containing count characters from 
source, beginning at source[index]. If counts<0, then a null string is returned. If 
index<1 or indext+tcount>length (source), i.e. if character positions outside the 
range 1. .length (source) are implicitly referenced, it is not an error. However, only the 
characters that lie within that range are copied. 


10.5.5 The Delete Procedure 
Deletes a substring of specified length from a specified position within the value of a string 
variable. 


Parameter List: delete(dest, index, count) 


e dest is a variable-reference that refers to a variable of a string-type. This is a variable 
parameter. 


* index is an expression with an integer-type value. 
* count is an expression with an integer-type value. 


Delete (dest, index, count) removes count characters from the value of dest, 
beginning at dest [index] . If index<1 or index+count>length (source), ie. if 
character positions outside the range * are implicitly referenced, it is motan error. However, 
only the characters that lie within that range are deleted. 


10.5.6 The Omit Function 
Deletes a substring of specified length from a specified position within a string value and 
returns the result. 
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Result Type: string-type 
Parameter List: omit(str, index, count) 


¢ str is a value of string-type. 
* index is an expression with an integer-type value. 
* count is an expression with an integer-type value. 


Omit (str, index, count) removes count characters from the value of str, 
beginning at dest [index], and returns the resulting string value. This is similar to 
delete except that str is not affected; the resulting string value is returned as the value of 
the function instead. 


10.5.7 The Insert Procedure 
Inserts a substring into the value of a string variable, at a specified position. 


Parameter List: insert(source, dest, index) 
* source is an expression with a value of string-type. 


¢ dest is a variable-reference that refers to a variable of string-type. This is a variable 
parameter. 


¢ index is an expression with an integer-type value. 


Insert (source, dest, index) inserts source into dest. The first character of 
source becomes dest [index] . If index<1 or index>length (dest) , itis motan 
error. If index<1 then source is appended to the left of dest. If index>length (dest) 
then source is appended to the right of dest. It is an error, however, if the length of the 
resulting string is greater than 255. 


10.5.8 The Include Function 
Inserts a substring into a string value, at a specified position, and returns the result, 


Result Type: string-type 
Parameter List: include(source, str, index) 


* source is an expression with a value of string-type. 


e str isa value of string-type. 


¢ index is an expression with an integer-type value. 
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Include(source, str, index) inserts source into the value of str al str [index] 
and returns the result. This is similar to insert except that str is not affected; the resulting 
string value is returned as the value of the function instead. 


10.6 THINK Pascal Window Manipulation Procedures 
10.6.1 The HideAll Procedure 


Parameter List: HideAll 


HideA11 causes all of the windows on the THINK Pascal desktop to be hidden. All of these 
windows may be revealed again with the Windows menu. In addition, the Text and Drawing 
windows may be revealed by calling the procedures described below. 


10.6.2 The ShowText Procedure 


Parameter List: ShowText 


ShowText causes the Text window to be revealed and to become the active window. The 
size and position of the window is unchanged. 


10.6.3 The ShowDrawing Procedure 


Parameter List: ShowDrawing 


ShowDrawing causes the Drawing window to be revealed and to become the active 
window. The size and position of the window is unchanged. 


10.6.4 The SetTextRect Procedure 
Parameter List: SetTextRect (WindowRect) 
¢ WaindowRect is a value of type Rect. 


WindowRect is a rectangle in QuickDraw’s global coordinate system that determines the 
position and size of the Text window on the Macintosh screen. 


10.6.5 The SetDrawingRect Procedure 


Parameter List: SetDrawingRect (WindowRect) 
° WindowRect is a value of type Rect. 


WindowRect is a rectangle in QuickDraw’s global coordinate system that determines the 
position and size of the Drawing window on the Macintosh screen. 


10.6.6 The GetTextRect Procedure 


Parameter List: GetTextRect (WindowRect) 
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¢ WindowRect is a variable-reference of type Rect. 


GetTextRect returns a rectangle in WindowRect with coordinates in QuickDraw’s global 
coordinate system. This rectangle indicates the current size and position of the Text window. 


10.6.7 The GetDrawingRect Procedure 
Parameter List: GetDrawingRect (WindowRect) 


e WindowRect is a variable-reference of type Rect. 


GetDrawingRect returns a rectangle in WindowRect with coordinates in QuickDraw's 
global coordinate system. This rectangle indicates the current size and position of the 
Drawing window. 

10.6.8 The SaveDrawing Procedure 

Parameter List: SaveDrawing (title) 


¢ title is a string-type value that must contain a valid file name for a file-structured 
device (see §9.5). 


SaveDrawing saves the contents of the Drawing window as a file that may be read by 
MacPaint. The title string contains the name of the picture file to be created. If a file by 
that name already exists, it is overwritten. 


Note: SaveDrawing actually saves the contents of the current QuickDraw 
GrafPort. However, unless you specifically change the current port to be 
another port, the current port will always be the Drawing window's GrafPort 
when your program is running. 


10.7 Bit operations 


These procedures and functions in this section operate on the bits of values. These functions 
and procedures actually generate inline code. 


10.7.1 BitAnd 


Result type: integer or longint 
Parameter list: BitAnd(aNuml, aNum2) 


¢ aNum1, and aNum2 are either integer or longint values. 


BitAnd returns aNum1l AND aNum2. If both of the arguments to BitAnd are integer, the 
result is integer. If one or both of the arguments is a longint, the result is a longint. 
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10.7.2 BitOr 


Result type: integer or longint 
Parameter list: BitOr(aNuml, aNum2) 


¢ aNuml, and aNum2 are either integer or longint values. 


BitOr returns aNum1 OR aNum2. If both of the arguments to Bit Or are integer, the result is 
integer. If one or both of the arguments is a longint, the result isa Longint. 


10.7.3 BitXor 


Result type: integer or longint 
Parameter list: BitXor(aNum1, aNum2) 


* aNum1, and aNum2 are either integer orlongint values. 


BitXor returns aNuml XOR aNum2. If both of the arguments to BitXor are integer, the 
result is integer. If one or both of the arguments is a longint, the result is a Longint. 


10.7.4 BitNot 


Result type: integer or longint 
Parameter list: BitNot (aNum) 


e aNumis eitheran integer orlongint value. 


BitAnd returns the one’s complement of aNum, that is, all the bits are inverted. If the 
argument to BitNot is integer, the result is integer. If the argumentis a longint, the 
result isa longint. 


10.7.5 BAND 


Result type: longint 
Parameter list: BAND(x, y) 


e xandy are scalar values of any size. Values smaller than 32 bits are zero extended. 
BAND returns x AND y. 


10.7.6 BOR 


Result type: longint 
Parameter list: BOR(x, y) 


e xandy are scalar values of any size. Values smaller than 32 bits are zero extended. 


BOR returns x OR y. 
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10.7.7 BXOR 


Result type: longint 
Parameter list: BXOR(x, y) 


e xandy are scalar values of any size. Values smaller than 32 bits are zero extended. 
BXOR returns x XOR y. 


10.7.8 BNOT 


Result type: longint 
Parameter list: BNOT (x) 


¢ xis a scalar value of any size. Values smaller than 32 bits are zero extended. 
BNOT returns NOT x, that is the one’s complement of x. 


10.7.9 BSL 


Result type: longint 
Parameter list: BSL(x, y) 


e xand y are scalar values of any size. Values smaller than 32 bits are zero extended. 
BSL returns x left-shifted by y bits. 


10.7.10 BSR 


Result type: longint 
Parameter list: BSR(x, y) 


* xandy are scalar values of any size. Values smaller than 32 bits are zero extended. 


BSR returns x right-shifted by y bits. 


10.7.11 BROTL 


Result type: longint 
Parameter list: BROTL(x, y) 


¢ xandy are scalar values of any size. Values smaller than 32 bits are zero extended. 
BROTL returns x left-rotated by y bits. The high order bits rotate the low order bits. 


10.7.12 BROTR 


Result type: longint 
Parameter list: BROTR(x, y) 
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e xandy are scalar values of any size. Values smaller than 32 bits are zero extended. 
BROTR returns x right-rotated by y bits. The low order bits rotate to the high order bits. 


10.7.13 BIST 


Result type: longint 
Parameter list: BTST(x, y) 


¢ xand y are scalar values of any size. Values smaller than 32 bits are zero extended. 
BTST returns true if bit y in x is set. The high order bit is bit 31; the low order bit is bit 0. 


10.7.14 BCLR 


Parameter List BCLR(x,y) 

e x isa var longint variable reference. 
e yis an integer reduced modulo 32. 
BCLR clears bit y of x. 


10.7.15 BSET 


Parameter List BSET (x,y) 

e xis avarlongint variable reference. 
ey is an integer reduced modulo 32. 
BSET sets bit y of x. 


10.7.16 HiWord 


Result Type: integer 
Parameter List: HiWord(long) 


¢ longisalongint value. 
HiWord returns the upper 16-bits of a longint value as an integer value. 


10.7.16 HiWrd 


Result Type: integer 
Parameter List: HiWrd (long) 


¢ longisalongint value. 
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HiWrd returns the upper 16-bits of a longint value as an integer value. 


10.7.16 LoWord 


Result Type: integer 
Parameter List: LoWord(long) 


* longisalongint value. 


LoWord returns the lower 16-bits of a longint value as an integer value. 


10.7.16 LoWrd 


Result Type: integer 
Parameter List: LoWrd (long) 


e longisalongint value. 
LoWrd returns the lower 16-bits of a longint value as an integer value. 


10.8 Control Procedures 
These procedures let you exit loops and routines. 


10.8.1 Cycle 
Cycle to next repetition of enclosing loop statements. 


Parameter list: Cycle 


Cycle goes to the next repetition of the enclosing while, repeat, or for statement. It can 
only be used within one of these statements, 


10.8.2 Leave 
Leave enclosing loop statements. 


Parameter list: Leave 


Leave goes to the statement following the enclosing while, repeat, or for statement. It 
can only be used within one of these statements, 


10.8.3 Exit 
Exit enclosing procedure. 


Parameter list: Exit (procName) 


* procName is the name of an enclosing procedure. 
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Exit returns from the procedure procName. ProcName must be the name of the procedure 
in which the statement appears, or it must nest the procedure in which it appears. 


10.8.4 Halt 
Exit the program 


Parameter list: Halt 
Halt exits the program, 


10.9 Miscellaneous Procedures and Functions 

10.9.1 The Sizeof Function 

Returns the number of bytes occupied by a specified variable, or by any variable of a 
specified type. 


Result Type: integer 
Parameter List: sizeof (id) 


¢ idis either a variable-identifier or a type-identifier. 


Sizeof (id) returns the number of bytes of memory occupied by id. Id cannot have any 
modifier (e.g. aRec. field). If idis a variable-identifier; if id is a type-identifier, it returns 
the number of bytes occupied by any variable of type id. 


10.9.3 The WriteDraw Procedure 
WriteDraw is similar to write, except that the text output goes to the current GrafPort 
at the current PenLoc instead of to a text file or to the Text window. 


Parameter List: WriteDraw(p; [, Po, «, Py ]) 


* Py, +, Pp, are write-parameters. Each write-parameter includes an output 
expression, whose value is to be written to the file. As explained in §9.4.3.1, a write- 
parameter may also contain the specifications of a field-width and a number of decimal 
places. Each output expression must have a result of char-type, an integer-type, a real- 
type, a string-type, a packed-string-type, or an enumerated-type. At least one write- 
parameter must be present. 


WriteDraw takes the same parameter list as write (see §9.4.3), except that no file 
parameter is ever given. The text that results from the evaluation of each write-parameter is 
written in the current GrafPort starting at the current pen position. 


Do not forget to set current PenLoc before using WriteDraw. 
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10.9.4 The StringOf Function 
StringOf is also similar to write, except that the text output is returned as a string-type 
value instead of being written to a textile or to the Text window. 


Result Type: string-type 
Parameter List: StringOf(p, [, Pa, ». Pn ]) 


° Pir -, Py are write-parameters, Each write-parameter includes an output 
expression, whose value is to be written to the file. As explained in §9.4.3.1, a write- 
parameter may also contain the specifications of a field-width and a number of decimal 
places. Each output expression must have a result of char-type, an integer-type, a real- 
type, a string-type, a packed-string-type, or an enumerated-type. At least one write- 
parameter must be present. 


StringOf takes the same parameter list as write (see §9.4.3), except that no file 
parameter is ever given. The text that results from the evaluation of each write-parameter is 
accumulated as a string-type value that is the result of the function call. 


10.9.7 The ReadString Procedure 
ReadSt ring is similar to read, except that the text is read from a string parameter instead 
of a textfile, 


Parameter List: ReadString(s, vy [, vg, =, V_ 1) 


* sis astring-type valuc. 
e Each v isa variable-reference that refers to a variable of one of the following types: 


° Char ora subrange of char. 

e An integer-type: integer (ora subrange) or longint. 

e Areal-type: real, double, extended, or computational. 
¢ An enumerated-type (including boolean) or a subrange . 

e Astring-type. 


ReadSt ring reads text from the string value s just as if it were doing a read (see §9.4.1) 
from a textfile. The values read are placed in the v parameters in the given order. Just as it is 
an error to attempt to read beyond the end of a file, it is an error to attempt to read characters 
beyond the end of the string value s. 


10.9.8 The OldFileName Function 
Returns the title of an existing disk file selected by the user. 
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Result Type: string-type 
Parameter List: OldFileName (Prompt) 


* prompt is a string-type value. 


OldFileName causes a dialog box to appear on the Macintosh screen. The Prompt string is 
not displayed. It is there for historical reasons, but must be supplied. With the dialog box, the 
user can peruse the existing files on any number of disks and select one of them. 
OldFileName returns a string value that is the title of the file the user selected, which can in 
turn be given to reset, rewrite, or open. 


10.9.9 The NewFileName Function 
Returns the title of a new disk file selected by the user. 


Result Type: string-type 
Parameter List: NewFileName(Prompt [, Default Name ]) 


* Prompt is a string-type value. 


NewFileName causes a dialog box to appear on the Macintosh screen. The Prompt string is 
displayed within this box to give the user some indication of what the box is asking for. With 
the dialog box, the user can select any disk and enter the name (or choose the default name) 
of a file to be created on that disk. NewFileName returns a string value that is the title of the 
file the user selected, which can in turn be given to reset, rewrite, or open. 


The Default Name string is displayed in the dialog box as selected text, and will be the 
string returned unless the user enters another name. 


10.9.10 The Synch Procedure 


Parameter List: Synch 


The Synch procedure is used to synchronize your program’s actions with the Macintosh 
screen’s drawing cycle, which occurs every 60" of a second. This may, in particular, be used 
to synchronize calls to QuickDraw with the screen drawing cycle to avoid unnecessary flicker 
and scanning bar phenomena when moving things around quickly in the Drawing window. 


When you call the synch procedure, the procedure will not return until the screen has 
reached the point in its cycle where the electron beam has returned to the top of the screen 
and is about to redraw the entire picture. Depending on where your QuickDraw calls are 
going to be drawing on the screen, additional delays may be necessary to synchronize the 
drawing with the timing of the electron beam’s scanning of the screen. 


10.9.11 The Note Procedure 


Parameter List: Note(Frequency, Amplitude, Duration) 
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* Frequency isan longint value in the range 12..783360. 
¢ Amplitude is an integer-type value in the range 0..255. 
¢ Duration is an integer-type value in the range 0..255. 


Note causes a single square-wave tone to be generated, of the given amplitude, duration, 
and frequency (the frequency is specified in hertz). 


10.9.12 The InLine Procedures 


Parameter List: InlineP(Trap [, Py, Po, -, Pp 1) 
BInlineF (Trap [, Py, Pa, -+ Pp 1) 
WInlineF (Trap [, Py, Po, », Pp 1) 
LInlineF (Trap [, Py, Po, ~, Pp J) 


¢ Trap is an expression with an integer value that indicates the number of the trap to be 
called. 


¢ Each p (if given) is an expression with any type value. 


The InLine procedures provides the ability to call the stack-based Macintosh Toolbox 
routines. The InLine procedures work by disabling all type and parameter checking normally 
used in THINK Pascal. This makes it possible for just four predefined routines to invoke any 
stack-based Toolbox trap. 


Toolbox routines can be either functions or procedures. Functions can return either a byte (8- 
bits), a word (16-bits), or a longword 32-bits as results. 


Toolbox functions can, depending on the result type, be invoked with one of the three 
following routines: 


¢ BinlineF — Toolbox functions which return a byte (boolean) 

¢ WInlineF — Toolbox functions which return a word (integer) 

¢ LInlineF — Toolbox functions which return a longword (longint) 
Toolbox procedures can be invoked with the following routine: 

e InlineP 


All procedures and functions use the same basic parameter-passing mechanism. Parameters 
are passed either by reference (variable parameters) or by value. To force a parameter to an 
InLine routine to be passed by reference, the @ operator may be applied to the name of the 
variable that is to be passed. For example, 
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@WindPtr 


will force a reference to WindPt r to be passed to a Toolbox routine. Simply using a variable, 
constant, or literal value will pass a parameter by value. 


The first parameter to any InLine call is the value which specifies the trap number. The trap 
number indicates which Toolbox routine is to be called. All subsequent parameters must 
exactly match the number and type of the parameters for the particular Toolbox routine 
being called. 


Warning: Because there is no type checking, none of THINK Pascal’s usual 
implicit type-coercion will be performed (e.g., integer to Llongint). All 
parameters must match exactly the parameters for the particular Toolbox 
routine being called. 


Note: The InLine procedures are provided only for compatibility with 
Macintosh Pascal. THINK Pascal provides direct access to the Macintosh 
toolbox and therefore the only need for InLine is for porting Macintosh 
Pascal programs which used these routines. 


10.9.13 The Generic Procedure 


Parameter List: Generic(InstructionWord, Registers) 


e InstructionWord is an expression with an integer value that indicates the instruction 
to be executed, 


¢ Registers is a variable-reference of type RegisterRecord (see below) that 
indicates the values to be written to the MC68000 registers. 


Generic lets you call register-based Macintosh ROM routines. It can also be used to execute 
any machine-language code that you have stored in a Pascal data structure. 


RegisterRecord denotes a data structure consisting of 13 32-bit values - five address 
register values (AO. .A4), followed by eight data register values (DO. .D7). The exact type of 
this structure is immaterial. For example, you could declare: 


var registers: record 
a: array[0..4] of longint; 
d: array[0..7] of longint 
end; 


The register values passed to Generic are written to the MC68000 registers. Then the one- 
word instruction denoted by the Inst ructionWord argument is executed. Finally, the 
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Registers structure is updated with the (possibly) new values of the MC68000 registers 
before Generic returns to the program. 


Usually, Generic will be used to execute a register-based Toolbox trap. In such cases, the 
value you pass to Generic via the Inst ruct ionWord argument is the trap value. 


The InstructionWord argument to Generic does not have to be a trap value, it can be 
any 16-bit MC68000 instruction. 


Note: The Generic procedure is provided only for compatibility with 
Macintosh Pascal. THINK Pascal provides direct access to the Macintosh 
toolbox as well as the ability to call assembly language routines. Therefore, 
the only need for Generic is for porting Macintosh Pascal programs which 
used this routine. 


10.9.14 The Macsbug Support Procedures 


Parameter list: Debugger 
DebugStr (message) 


° Message is a string-type value. 
Debugger and DebugSt r cause a User Break which interrupts the execution of the 
program and transfers control to the Macsbug low-level debugger. If DebugSt r is used, the 


message argument is displayed. 


If Macsbug is not installed, then calls to Debugger and DebugSt rr give the run time error 
message “Macsbug/TMON not installed.” 


Refer to Appendix F for more information on using Macsbug. 


10.9.16 Member function 


Parameter list: Member(r, t) 
¢ xis an object-reference expression 
e tis atype-identifier of a reference type 


Member returns true if r references an object of type t. 


346 


THINK’s 


Lightspeed Pascal 


PART FIVE 


Appendices 


A ANS Pascal Compatibility 
B Porting to THINK Pascal 
C BackupProject 

D RMaker Reference 

E Error Messages 

F Macsbug Reference 


ANS Pascal Compatibility 
A 


Introduction 


This appendix describes the relationship between THINK Pascal and the requirements of 
ANSI/IEEE770X3.97-1983, American National Standard Pascal (ANS Pascal). (An American 
National Standard IEEE Standard Pascal Computer Programming Language (IEEE, Wiley- 
Interscience)) 


Exceptions to ANS Pascal Requirements 


THINK Pascal complies with the requirements of ANSI/IEEE770X3.97-1983 with the follow- 
ing exceptions: 


¢ In ANS Pascal, the special-symbol @ is an alternative representation for the special-sym- 
bol *, and is required to be treated identically to * wherever it appears. In THINK Pascal, 
the special-symbol @ is an operator and is never treated identically to *. 


e In ANS Pascal, identifiers may be of any length and all characters are significant. In 
THINK Pascal, all characters in identifiers are significant, but the largest identifier is re- 
stricted to 255 characters. 


e In ANS Pascal, a character-string of length 1 is a char-type value and a character-string of 
length n is a value of a packed-string-type (a packed array [1..n] of char — 
referred to as a string-type in ANS Pascal) with n components. In THINK Pascal, all 
quoted character-strings are string-type values. However, the compatibility and assign- 
ment-compatibility rules in THINK Pascal make its behavior with respect to character- 
strings compatible with ANS Pascal. 


* In ANS Pascal, all values of a tag type must appear once for a given variant part. In 
THINK Pascal, this requirement is not enforced. 


¢ In ANS Pascal, a function block must contain at least one assignment statement assigning, 
a value to the function identifier. In THINK Pascal, this requirement is not enforced. 


e In ANS Pascal, a field that is the selector of a variant part of a record may not be an actual 
variable parameter. In THINK Pascal, this requirement is not enforced. 
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In ANS Pascal, no statements that threaten the value of a control-variable of a for-state- 
ment are allowed. In THINK Pascal, this requirement is not enforced. Changing the value 
of the control variable produces indeterminate results. 


In THINK Pascal, only the standard file variables input and output are allowed as pro- 
gram parameters. 


In THINK Pascal, the range of integers is -32768..32767 (-maxint-1l..maxint) 
In THINK Pascal, the mod performs a simple remainder, not a true modulo operation. 


Note: There is no automatic means, in THINK Pascal, of determining 
whether or not a program violates any of the exceptions listed above. 


Extensions to ANS Pascal 


The following THINK Pascal features are extensions to Pascal as specified by 
ANSI/IEEE770X3.97-1983: 


Note: These extensions are described more fully in Appendix B. 
The following are word-symbols in THINK Pascal: 


implementation otherwise 


inherited string 
inline unit 
interface uses 
object 


An identifier may have an underscore appearing anywhere following the initial leer of 
the identifier. 


THINK Pascal supports relaxation of the ordering of declarations. There may be any 
number of declaration parts in any order. 


THINK Pascal supports the additional integer-type Longint and the additional real- 
types double, computational, and extended. 


A signed constant-identifier may denote a value of type integer, longint, or 
extended. 


In THINK Pascal, the result of arithmetic performed on integer operands is integer. 
The result of arithmetic performed on Longint operands is longint. All mixed 
integer and longint operands are converted to longint before arithmetic is per- 
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formed, and the result is longint. A longint value may be used wherever an 
integer value is required if the value falls in the range -maxint..maxint. 


All integer-type and real-type operands are converted to ext ended before any real 
arithmetic is performed, and the result is always extended. An extended value may 
be used wherever a real, double, or computational value is required, provided 
the value falls within the range of values permissible. 


THINK Pascal supports string-types, which are compatible with other string-types, 
packed-string-types, and char-type. 


In THINK Pascal, the assignment-compatibility rules have been extended to allow the 
mixing of string-types, packed-string-types, and char-type where appropriate, 


The result-type of a function is not restricted to simple and pointer-types; functions may 
return values of any type. 


Individual char-type components of string-type variables may be referenced as though 
the string were a one-dimensional array. 


String-types may be compared with char-type and packed-string-type values. 


The @ operator is provided for obtaining the address of a variable, procedure, or 
function. 


THINK Pascal has an optional otherwise clause for the case-stalement. 


THINK Pascal supports the use of the indefinite-string-type, i.e. the word-symbol 
string, as a value or variable-parameter type. 


An optional second parameter may be given to reset and rewrite to associate a file 
variable with an external file. 


Instead of reset or rewrite, a file may be opened with open to allow random 
read/write access to a file. 


An explicit cLose procedure is supplied for those file variables associated with external 
files. 


A seek procedure may be used for random-access to file components. 


A £ilepos function returns the component number of the current file position, a value 
that may be used in subsequent seeks. 


String-type and enumerated-type values may be read from textfiles with read and 
readin. 
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String-type and enumerated-type values may be written to textfiles with write and 
writeln. 


Lazy 1/O is used to permit interactive and non-interactive I/O to be treated identically. 


In THINK Pascal, the ord function may be applied to a pointer-type value, facilitating 
address arithmetic. 


The ord4 function is provided in THINK Pascal for converting an ordinal-type or 
pointer-type value toa longint. 


The pointer function is provided in THINK Pascal for converting an integer-type value 
to a pointer-type value. 


THINK Pascal includes a set of string procedures and functions. 

The sizeof function is provided for obtaining the storage size of a variable or type. 
Inline routines are supported for imbedding machine code in a program. 

Units are supported for modular construction of programs and separate compilation. 
THINK Pascal supports type-casting of values. 


THINK Pascal supports all of the Macintosh Toolbox/OS constants, types, variables, pro- 
cedures, and functions as predefined identifiers. 


THINK Pascal supports Object Pascal extensions as described in Object Pascal Report, by 
Larry Tesler. Apple Computer 1985. 


THINK Pascal allows constant expressions in const declarations. 
THINK Pascal allows ranges for case labels. 

THINK Pascal supports short circuit boolean operators & and |. 

THINK Pascal supports the predefines cycle, exit, leave, and halt. 


Note: There is no automatic means, in THINK Pascal, of distinguishing be- 
tween a program that uses extensions and one that does not. 


Implementation-Dependent Features 


The effect of using an implementation-dependent feature of Pascal, as defined by 
ANSI/IEEE770X3.97-1983, is unspecified as described in the preface to the Language 
Reference. 
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Treatment of Errors 


This section defines those errors listed in Appendix D of the ANS Pascal standard that are nol 
automatically detected and reported by THINK Pascal. The number of each error listed below 
is the number under which the error is listed in the standard's appendix. The wording of the 
description of the error, however, differs from the wording in the standard. 


2. If t is the tag-field of a variant-part, and if £ is a field within the currently active variant of 
that variant-part, then it is an error to attempt to alter the value of t while a reference to f 
exists. 


4. Ifp isa pointer-type value, it is an error to reference p* if the value of p is undefined. 


5. Ifp isa pointer-type value, it is an error to attempt to dispose of p while a reference to 
p* exists. 


6. If £ isa file-type variable, it is an error to attempt to close f or alter the current file posi- 
tion of £ while a reference to £* exists. 


19. If a pointer-type variable p is assigned a value by new (p,c,,C9,.-.,C,), iis an error 


to attempt to make any other variants than those selected by the case-constants in new 
become the active variant. 


20. If a pointer-type variable p is assigned a value by new (p,c1,C9,-.-,C,), itis an error 


to attempt to dispose of p without supplying the same list of case-constants in the same 
order. 


21. Same as 20. 
22. Same as 20. 
24, Itis an error to attempt to dispose of p if the value of p is undefined. 


25. Ifa pointer-type variable p is assigned a value by new (p,C,,C9,---,Cy), itis an error 


to reference the entire variable p* in an expression, as an actual variable-parameter, or 
as the destination of an assignment-statement. 


27. For pack (a, i, 2z), itan error if any of the referenced components of a have undefined 
values. 


30, For unpack (z,a,i), itis an error if any of the components of z have undefined 
values. 
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speed Pascal 


For chr (x), the function returns a result of char-type which is the value whose ordinal 
number is equal to the value of the expression x if such a character exists. It is an error if 
such a character value does not exist. 


. For succ (x), the functions yields a value whose ordinal number is one greater than that 


of x, if such a value exists. It is an error if such a value does not exist. 


. For pred (x), the functions yields a value whose ordinal number is one less than that of 


x, ifsuch a value exists. It is an error if such a value does not exist. 


. Itis an error to reference a variable in an expression if the value of that variable is 


undefined. 


. Itis an error if the result of the activation of a function is undefined when that activation 


is complete. 


. Itis an error if none of the case constants is equal to the value of the case index upon 


entry to a case statement. 


Porting to THINK Pascal 
B 


Introduction 


Pascal was designed by Professor Niklaus Wirth primarily as a tool for teaching systematic 
programming. It has evolved into one of the most popular programming languages, the main 
attraction being its emphasis on rigid structure and strong typing. In the evolution process 
most Pascal implementations have added a number of language extensions. Since most ex- 
tensions are unique to a particular implementation, some work is required to port Pascal 
programs from one computer to another. 


Different implementations have interpreted the semantics of the unadorned language in dif- 
ferent ways. This issue was addressed by the Joint ANSI/X3J9-IEEE Pascal Standards 
Committee, which in 1982 approved a standard language (informally called ANS Pascal) to 
promote the portability of Pascal programs between implementations. 


THINK Pascal is intended to conform, as closely as possible, to ANS Pascal (see Appendix A), 
while providing extensions necessary for the development of serious Macintosh applications. 
THINK Pascal tries to keep such extensions to a minimum, choosing features common to 
many Pascal implementations, while retaining compatibility with existing systems, notably 
Macintosh Programmer's Workshop (MPW) and Macintosh Pascal. 


This appendix is designed to help you port existing programs to THINK Pascal. It provides a 
comprehensive list of areas in which THINK Pascal may differ from other implementations, 
along with suggestions for modifying programs to run under THINK Pascal. 


Program Size 


THINK Pascal limits the size of any individual source file to around 2500-4000 lines depend- 
ing on line density. This limitation provides improved edit and compile performance, and re- 
lates well to inherent limitations such as segment size. However, programs developed using 
other compilers may consist of larger source files, particularly those developed without the 
benefit of separate compilation. 


If you attempt to load a file that exceeds this limitation, THINK Pascal warns thal some lines 
have been lost. The best approach is to use a good text editor to break the file up into smaller 
units. 
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Ifa large file contains procedures and functions which are to be allocated in different seg- 
ments (which is typical in MPW Pascal programs) you should break up the file based on its 
required segmentation. See the section on Segmentation below. 


Identifier Length 


Most Pascal compilers only check the spelling of identifiers up to 8 or 16 characters. In 
THINK Pascal, all characters in an identifier are significant, up to the maximum length (255). 
For example, many compilers don’t report an error with this code: 


var 

aVeryVeryLongName: integer; 
begin 

aVeryVeryLongNme := 0; 
end; 


THINK Pascal reports the misspelling as an undeclared identifier. 


Reserved Words 


THINK Pascal has added the following word-symbols which may not be used as identifiers: 


implementation otherwise 


inherited string 
inline unit 
interface univ 
object uses 


If you try to use one of these reserved words as an identifier, THINK Pascal reports an error. 


Comments and Directives 


Some Pascal compilers treat the comment delimiter pairs { } and (* *) differently, allow- 
ing comments which use one delimiter to be “commented out” with the other delimiter. For 
example, in MPW Pascal the code sequence 


if ResError <> noErr then {report resource error} 
alertStatus := Alert (MyRsrcAlert, nil); 
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could be commented out like this: 


(* if ResError <> noErr then {report resource error} 


alertStatus := Alert (MyRsrcAlert, nil); 
*) 


THINK Pascal treats the different comment delimiter pairs the same, so you can’t nest com- 
ments. Also, comments may not cross line boundaries. THINK Pascal converts multi-line 
comments into several single line comments. Nested comments may not be converted 
correctly. 


You can use the conditional compilation commands to comment out large blocks of code or 
to simulate multi-line comments like this: 


{SIFC FALSE} 
code to ignore 
{ SENDC} 


Most Pascal implementations support special compiler directive comments. These com- 
ments are typically of the form {$x+} or {$x-}, where x is a one or two character 
mnemonic for the particular option. THINK Pascal supports a number of compiler directives; 
these are described in detail in Chapter 15. 


Compiler directives are not addressed in the ANS Pascal standard, so they vary greatly be- 
tween implementations. For example, the MPW Pascal compiler supports: 


{$I filename} include filename in text 

{SS segmentname} place code in segment segmentname 
{SOV+} turn on overflow checking 

{$R-} turn off range checking 


MPW also supports other compiler directives, most of which have no analog in THINK 
Pascal. It is best to assume that all compiler directives are not portable, and should be 
changed or removed. 


Note: You can enable and disable most of the THINK Pascal compiler 
directives from the Project window. 


Types 


Different implementations of Pascal place different limitations on predefined and user de- 
fined data types. These limitations typically reflect the chosen representation of data, or con- 
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straints imposed by the underlying hardware architecture. For example, the ANS standard re- 
quires that the type integer contain all values in the range -maxint to maxint, but ac- 
cepts the fact that these values are machine dependent and may differ across implementa- 
tions, 


THINK Pascal imposes the following data type limitations: 


¢ Integers are limited to the range -32768 to 32767. 
e Enumerated types may contain no more than 256 distinct values. 


You can declare array types larger than 32K, but the total size of all the variables in a block 
cannot exceed 32K. Suppose you wanted to create a large array. Here’s one way: 


type 
BigAry = array [0..99999] of integer; 
BigAryPtr = *“BigAry; 
BigAryHandle = “BigAryPtr; 


var 
myBigAry : BigAry; { this is NOT allowed! } 
myBigAryH : BigAryHandle; { but this is } 
i: integer; 
begin 
myBigAryH := BigAryHandle (NewHandle (sizeof (BigAry) )); 
for i := 0 to 99999 do 
myBigAryH**[i] := 0; 
end; 


There are also areas in which THINK Pascal exceeds limitations imposed by other Pascal im- 
plementations. For example: 


* Support for the fullset of integer including negative-value elements. 

¢ Support for floating-point values of single, double, computational and ex- 
tended precision. 

¢ String-types, packed-string-types, and char-type are completely compatible. 


For a complete description of all THINK Pascal data types, refer to Section 3 of the Language 
Reference. 


Data Representation 


The way a Pascal compiler represents data depends on hardware differences and personal 
judgment. THINK Pascal follows the Macintosh Toolbox conventions for ordinal types. For 
example, the integer type is a 16 bit value to take advantage of the more efficient 16 bit 
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instructions of the MC68000. The 32 bit integer type Longint is provided for dealing with 
values which exceed the range of 16 bit integers. 


The data type char is also implemented as a 16 bit (rather than the more natural 8 bit) value. 
It occupies 8 bits only when packed. There are some subtle ramifications of this implementa- 
tion. The predefined type text is usually assumed to have the same representation as file 
of char; Macintosh Pascal assumes that this is the case. In THINK Pascal, text has the 
same representation as packed file of char. This may cause difficulty when porting 
programs which use file of char. 


The MPW Pascal compiler provides a more comprehensive packing algorithm than THINK 
Pascal; for example, the type definition 


type 
KeyMap = packed array [0..127] of boolean; 


causes each element of a KeyMap lo occupy one bit. THINK Pascal never does bit-packing, 
so this type is implemented differently: 


type 
KeyMap = array [0..3] of longint; 


Programs which depend upon bit-packing of data are not portable to THINK Pascal without 
modification. 


The representation of data in THINK Pascal is described more completely in Chapter 13. 


Data Initialization 


Some Pascal implementations guarantee specific values for uninitialized variables. For exam- 
ple, Macintosh Pascal initializes all global and local variables (and function results) to 0. 
THINK Pascal never initializes variables. Programs which (inadvertently) depend on variables 
being initialized may run into unusual run-time behavior. 


Operators 


The implementation of operators in THINK Pascal conforms for the most part to the ANSI 
standard, differing only in areas where THINK Pascal provides additional data types (e.g. 
string, longint, extended). Porting difficulties may occur in expressions involving in- 
teger arithmetic overflow (see the following section). 


For compatibility with MPW Pascal and other Pascal compilers, THINK Pascal implements the 
mod operator as a simple remainder operator. 
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Note: Earlier versions of THINK Pascal implemented the mod operator ac- 
cording to the rules for modulo arithmetic. 


Many compilers support an exponentiation operator ** for integer or floating-point 
operands. In THINK Pascal, floating-point exponentiation can be easily implemented, based 
on the following identity: 


x ** y = Exp (Ln (x) * y) 


If you port a program which uses integer exponentiation, you may have to write a simple ex- 
ponentiation function. 


Integer Arithmetic 


THINK Pascal performs all integer arithmetic in either 16 bits or 32 bits depending on the 
type of the operands. For binary operators, if both operands are 16 bits (or smaller) the oper- 
ation is performed in 16 bits; if either or both operands is 32 bits, the operation is performed 
(less efficiently) in 32 bits. 


Consider the implications of these arithmetic rules on this piece of code: 


var 

i, j: integer; 
begin 

i 20000; 

3 30000; 

writeln (i+}); 
end; 


ou 


This program fragment will cause an overflow error in THINK Pascal because the sum 
20000+30000 is too large to be represented in 16 bits. Other implementations (notably 
Macintosh Pascal) may perform the operation in 32 bits, avoiding the overflow at the expense 
of execution efficiency. You can force the arithmetic to be performed in 32 bits by casting the 
operands to longint or by using the Ord4 function. 


A similar problem arises in programs ported from Macintosh Pascal which use inline proce- 
dures and functions (InlineP, BInlineF, WInlineF, LInlineF). The statement 


InlineP ($A9D1, 0+0, 65535, hTE); 
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attempts to call TESet Select with a longword 0 for selStart. In THINK Pascal, this re- 
sults in a word 0 being pushed instead, misaligning the stack and (probably) resulting in a fa- 
tal error. You can cast the integer value to a longint. Statements like the one above are 
better replaced by a call to the equivalent Macintosh Toolbox routine: 


TESetSelect (0, 65535, hTE); 


This call performs the proper argument type checking and conversion, and it’s easier to un- 
derstand and more efficient. 


Program Parameters 


THINK Pascal only allows the standard file-variables input and output as program- 
parameters. Occurrences of other file-variables in a program heading are reported as errors. 
These can be removed without affecting the semantics of the program. 


Predefined Procedures and Functions 


THINK Pascal, like Macintosh Pascal, provides a large number of predefined procedures and 
functions in addition to those required by the standard. Routines have been added to facili- 
tate address arithmetic, string handling, I/O, and other common tasks. On top of this, nearly 
all of the procedures and functions (and constants and types) described in Inside Macintosh 
are supplied as predefines (some are supplied as units: see below). 


Different implementations of Pascal are likely to provide different predefined procedures and 
functions, many of which have functional analogs in THINK Pascal. Programs that depend on 
nonstandard predefines will require modification. For example, the following MPW Pascal 
predefines are not supported: 


fillchar release 
mark scaneq 
moveleft scanne 
moveright 


For a complete description of the THINK Pascal predefines, see Chapter 17, §10. 


Standard Units 


Pascal compilers for the Macintosh typically provide a standard set of units, libraries, or in- 
clude files which define some or all of the constants, types, procedures, etc., described in 
Inside Macintosh, and whose declarations can be made available to any program or unit. For 
example, most MPW Pascal programs begin with the following uses-clause: 
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uses 
MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf; 


Similarly, Macintosh Pascal programs often start with: 


uses 
QuickDrawl, QuickDraw2; 


In THINK Pascal, most of the declarations in Inside Macintosh are predefined, and these 
uses-clauses are not required. 


Note: You can use MemTypes, QuickDraw, OSIntf, ToolIntf, and 
PackIntf if you add these files to your project. (They’re provided in your 
THINK Pascal package.) Most of these files contain no definitions. They’re 
included to make it easier to port from MPW Pascal. 


Some of the nside Macintosh declarations, such as the AppleTalk Manager, are supplied as 
libraries. Each is supplied as two files: a source (interface) file, and a library (code) file. Both 
of these files must be added to the project. The interface to the library is in the form of a unit. 
The unit name must appear in a uses-clause in the file that accesses the library. Methods for 
using these libraries are described in Chapter 11 of the User's Guide. The exact syntax for 
units is described in §8.3 of Chapter 17. 


Input/Output 


This is an area in which many Pascal implementations diverge, particularly in their treatment 
of interactive 1/O. THINK Pascal supports 1/O with ANS Pascal semantics and the following 
extensions: 


e An optional second parameter may be given to reset and rewrite to associate a 
file variable with an external file. A file opened with reset or rewrite is read-only 
or write-only respectively, and in both cases the file may only be accessed sequen- 
tially. 


° Instead of reset and rewrite, a file may be opened with open to allow random 
read/write access. 


¢ The seek procedure may be used for random-access to file components. 


e The filepos function returns the component number of the current file position, a 
value that may be used in a subsequent seek. 


¢ String-type and enumerated-type values may be read from text files using read and 
readin. 


Porting to THINK Pascal B 


¢ String-type and enumerated-type values may be written to text files using write and 
writeln. 


* Lazy I/O is used to permit both interactive and non-interactive I/O to be handled 
identically. 


THINK Pascal is identical to Macintosh Pascal in its treatment of I/O. Other compilers are 
likely to have different extensions. Programs which read and write to the predefined file vari- 
ables input and output interactively may cause some difficulty; see Section 9 of the 
Chapter 17 for a complete explanation of Lazy I/O and its ramifications. 


Segmentation 


Macintosh programs are usually composed of a number of segments, each of which can 
contain up to 32K of code. Segmentation allows programs to be written which are too large 
to fit in memory; segments can be loaded and unloaded as needed. 


Most Pascal implementations for the Macintosh support segmentation. In MPW Pascal seg- 
mentation is done on a procedure by procedure basis with a compiler option. 


These directives place the code for procedure PrintFile in segment PrintSeg, and the 
code for procedure CloseFile in segment FileSeg. 


{$S PrintSeg } 
procedure PrintFile (whichFile: integer) ; 
begin 


end; 


{SS FileSeg } 
procedure CloseFile (whichFile: integer); 
begin 


end; 
In THINK Pascal, programs are divided into segments on a file by file basis. The Project win- 
dow, when viewed by segment, shows which files are in which segment, and provides a vi- 


sual metaphor (dragging) for moving files between segments. If you are porting a program in 
which a single file contributes to multiple segments, some reorganization will be necessary. 
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Run Time Environment 


Macintosh programs usually begin with a sequence of initialization calls to various portions of 
the Macintosh Toolbox. In THINK Pascal, the following initializations are performed 
automatically for your application: 


InitGraf (@thePort) ; 

InitFonts; 

InitWindows; 

InitMenus; 

TEInit; 

InitDialogs (nil); 

SetApplLimit (<current value of A7> - <Run Options stack size>); 
MaxAppl1 Zone; 


If you initialize the Macintosh Toolbox manager explicitly in your program, use the { $I-} 
directive to turn off the automatic initialization (see Chapter 15). 


Extensions 


THINK Pascal supports several extensions to the Pascal language. 


Control procedures 
These procedures let you control the flow of your program without resorting to goto state- 


ments. 
cycle go to the next repetition of the enclosing while, 
repeat, or for statement 
leave go to the statement following the enclosing while, 
repeat, or for statement 
exit (procname) exit the named (enclosing) procedure 
halt exit the program 


Constant expressions 


Constant expressions are allowed only in const declarations. They must evaluate to 
integer, char, boolean, or enumerated type. 


Example: 


const 
limit = maxSize - 1; 
CR = Chr ($0D); 
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Case label subranges 
A case label in a case statement may be a range of constant values: 


case today of 
monday. .friday: 
saturday: 
sunday: 

end; 


Generalized function results 
Function calls may be treated as simple variables. 


Example: 


var 
myHandle: Handle; 


myHandle := InfoScrap”.scrapHandle; 


Type casting 


Type casts may be applied to I-values (variable-references appearing on the left-hand-side of 
an assignment, or as an actual var parameter) as well as r-values (variable-references ap- 
pearing in expressions). For example: 


var 
myHandle: Handle; 
hTE: TEHandle; 


myHandle := hTE**.hText; 

CharsHandle (myHandle)**[0] := Chr($OD); 
DrawChar (CharsHandle(myHandle) **[0]); 
DisposHandle (myHandle) ; 


Short circuit Booleans 


THINK Pascal uses the & and | operators for minimum evaluation of boolean expressions. In 
this statement: 


if (p <> nil) & (p*.name = '') then... 


The second test (p*.name = '') is performed only if the first test (p <> nil) evalu- 
ated to true. 
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Introduction 


This appendix describes BackupProject, a utility program that comes with your THINK Pascal 
package. BackupProject lets you back up all the files in your project to a floppy disk or to 
another folder on your hard disk. BackupProject is faster than using the Finder to back up 
your project. It’s also better because it backs up all the files in the project including libraries 
and resource files. 


Topics covered in this chapter: 
¢ Using BackupProject 
¢ Working with files 
¢ Tips 


Using BackupProject 


To start BackupProject, double-click on its icon in the Finder. When the BackupProject 
menus appear, choose Open Project... from the File menu. Use the standard file dialog to 
choose one of your THINK Pascal projects. You'll see a BackupProject window like this: 


ditor Projec 


Project contains 11 files. 
268K bytes (maximum) to be backed up. 


Backed Up File Type File Size File Name 
Pascal Library 30228 Interface lib 
Pascal Library 33602 Runtime.lib 
Source File 2681 Editor Globals 
Source File 4015 Editor Init 
Source File 5029 Show Edit 
Source File 7731 Change Font 
Source File 22397 Editor Utilities 
Source File 31805 Editor TopLevel 
Source File 996 Editor Main 
Project File 134865 Editor Project 


v 
v 
v 
¥ E 
v 
v 
v 
¥ 
v 
v 
v 
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The BackupProject window shows you the type, size, and name of every file in your project. 
The first column shows you the last time the project was backed up. The check marks along 
the left edge of the window let you know which files BackupProject is going to back up. 


In the picture above, none of the files have ever been backed up, so BackupProject puts a 
check mark next to every file. You can click in the check mark column to check and uncheck 
a file. In the next section, “Working with Files,” you'll learn how to check and uncheck 
groups of files. 


Choosing a destination 


When you're sure all the files you want to back up are checked, click the Back Up button. 
You'll see this dialog box: 


G TextEd Demo 


© Wednesday Backup 


BackupProject lets you save your project's files to a set of floppies or to a folder on your hard 
disk. The destination dialog box works pretty much like a standard file dialog box. The mes- 
sage at the bottom of the dialog tells you what folder your file will be backed up to. The Back 
Up button tells BackupProject to go ahead and do the backup. The Open button lets you 
open a folder. If you select a folder and click on the Back Up button, the files will be placed 
in that folder. You can use the New Folder button to create a new folder without having to go 
back to the Finder. 


Note: This sounds more confusing than it is. The message at the bottom of 
the dialog box always tells you where your files will go when you click the 
Backup button. 


BackupProject Cc 


Copying the files 

BackupProject displays its progress at the top of the window. As it copies the files, 
BackupProject unchecks them, and notes the backup date and time in the project document. 
The next time you back up your project, BackupProject checks only the files that have 
changed since the last backup. Of course, you can check and uncheck any other files 
yourself. 


Note: If you use the Remove Objects command on your project, THINK 
Pascal removes the backup information as well. It will be as if you had never 
backed up the project. 


If you’re backing up to a floppy, BackupProject displays a dialog box asking you to insert 
another floppy when the first one is full. 


Occasionally, BackupProject may have a problem copying a particular file. If there is a disk 
error, BackupProject asks you if you want to skip the file that caused the problem, or if you 
want to try a different disk. If you think the problem is with the source (the file being 
copied), then skip the file. If you think the problem is with the destination (the disk you're 
copying to), then try a different disk. 


If the destination folder or disk already has a file with the same name as one of the files in 
your project, BackupProject asks you what to do: 


The file "Show Edit" already exists. What do you 
want to do? 


Replace File 


Change Disk 


(Don't ask again Cancel Backup 


You can choose to skip the file, replace the file, change disks, or cancel the entire backup. If 
you check the box marked “Don’t ask again,” BackupProject will do the same things when- 
ever it runs into the problem again. For instance, if you check “Don’t ask again” and then 
click on the Replace File button, BackupProject replaces files in the destination folder with 
copies of your project’s files whenever it finds duplicate names. 
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Working with Files 


Usually, you'll want to let BackupProject take care of choosing which files need to be backed 
up. Sometimes, though, you want to choose the files to back up yourself. BackupProject 
gives you several ways to choose which files get backed up. 


BackupProject lets you select any number of files. You select files in BackupProject the same 
way you do in the Font/DA Mover: 


To select... Do this... 

A single file Click on the file name 

A continuous range of files Hold down the Shift key and click on a file name 
Several individual files Hold down the Command key as you click on each file 


Once you've selected them, you can use the Check Selection and Uncheck Selection 
commands in the Backup menu to check and uncheck the selected files. You can also 
double-click on any of the selected files to toggle the check mark for all the files in the 
selection. 


You can use the Select C Libraries, Select Pascal Libraries, Select Source Files, and 
Select MPW Object Files, commands in the Backup menu to select files that meet certain 
criteria. Then you can use the Check Selection and Un-Check Selection commands on 
those files. 


The Select Files From command gives you a hierarchical menu which lists all the folders 
that your project references. You can use this command to select files from a particular direc- 
tory. For example, here’s one way of excluding the standard THINK Pascal libraries from 
your backup: 


* Choose Check All from the Backup menu 

* Choose Select Files From and choose the directory that contains the standard li- 
braries. (This is usually the THINK Pascal folder.) 

* Choose Un-Check Selection 


Tips 
Here are some tips to help you get more out of BackupProject. 


BackupProject and MultiFinder 


BackupProject works under MultiFinder, but it won't copy files in the background, and you 
can’t back up a file that’s already open in THINK Pascal. BackupProject uses all available 
memory to copy files, so if you make its partition bigger, your backups will be faster. 


BackupProject Cc 


Backup records 

The Write Backup Report... command in the Backup menu writes the contents of the 
BackupProject window as a text file. Use this command after you back up your project so 
you can have a handy record of what files were backed up when. Since you can read the re- 
port with any text editor (@Edit is great for this), you don’t have to start up BackupProject to 
check the status of your last backup. 


Large files 

BackupProject won't split large files — files that won't fit on a single floppy. The only file that 
might tend to be large in your project is the project document itself. You can get around this 
problem two ways. Don't back up the project document, or do a Remove Objects before 
you back up the project to make the project document as small as possible. 


Missing files 

If BackupProject can’t find a file that’s referenced in your project, it displays its name in italics 
and writes an error number in the check mark box. BackupProject skips over these files 
when it does a backup. 
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Introduction 


Macintosh programs are designed around objects. Windows, menus, dialog boxes, and alerts 
are all objects that the Macintosh uses. You can build these objects on the fly in your pro- 
grams, or you can load them in from the resource fork of your application. The advantage of 
storing these Macintosh objects as resources is that your program’s function (the code) is 
separate from the user interface (the look). 


RMaker is a resource compiler. It takes a textual specification of the objects to be used in a 
program and produces the resource data structures which are understood by the Macintosh 
Toolbox routines. 


To learn how to use resources with THINK Pascal projects, read the “Using Resource Files” 
section in Chapter 12. To learn about resources read Imside Macintosh I, Chapter 5, “The 
Resource Manager.” 


Topics covered in this appendix 
e Using RMaker 
e RMaker file format 
e Predefined resource types 


Using RMaker 


To create a resource file, use a text editor to create the RMaker source file. You can use the 
@Edit desk accessory included in your THINK Pascal package, or any word processor as long 
as you save the file as text only. 


When you launch RMaker, it displays a file selection dialog. Choose your RMaker source file, 
and RMaker will produce a resource file from it. 


RMaker File Format 


RMaker input is line-oriented and has a quite rigid syntax. The RMaker input file consists of 
an output specification followed by an arbitrary number of resource definitions separated by 
blank lines. Comments are also allowed, either as whole lines or as tags at the end of lines. 
Comment lines begin with an asterisk (+) . Comments at the end of lines are preceded by two 
semicolons (; ; ). 
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All numbers in your file are decimal, except in certain resource type declarations (see below). 
To enter special characters, use a backslash followed by two hexadecimal digits. For exam- 
ple, the code for the Apple (@) symbol is \14. A ++ at the end of a line tells RMaker that the 
line is continued on the next line. 


You can use the /QUIT directive to tell RMaker to quit after it builds your resource file. The 
/NOSCROLL directive tells RMaker not to scroll your file in its source window. For example: 


/QUIT 

/NOSCROLL 
FileName 
22? ?SAMP 


* resource declarations here... 


Output file specification 
RMaker files begin with the output specification. The name of the output file appears on the 
first line, followed by the file signature. The file signature is a four-character file type fol- 


lowed by a four-character creator. To learn more about file signatures, see Inside Macintosh 
Il, Chapter 1, “The Finder Interface.” 


For example, if you want to name the output file Sample and give it the file type ???? and 
creator SAMP, the first two lines of the RMaker input file would be: 


Sample +7 the name of the output file 
2???SAMP 7; the file type ???? and creator SAMP 


The file signature line may be left blank, in which case the file type and file creator will be set 
to nulls (four bytes of 0 each). The output specification may be preceded by an arbitrary 
number of blank lines or comment lines. 


If the file name begins with an exclamation point (!) , RMaker merges the resources into 
that file instead of creating a new file. In this case, if you don’t supply a file signature, RMaker 
leaves the file signature alone. 


You can use the INCLUDE filename statement to merge the resources from another re- 
source file into the output file. 


Resource declarations 


The body of an RMaker source file consists of groups of resource declarations headed by a 
resource type clause. 


(Note: in the following examples, the brackets [] enclose optional data. Words in italics de- 
scribe user-supplied data.) 
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A resource type section begins with a TYPE declaration: 


TYPE resource type [= resource type ] 


The = clause lets you define your own resource types. If the optional = clause is not present, 
the first resource type must be a predefined type. If the clause is present, the resource type 
named there must be a predefined type. 


The resource declarations come after the TYPE declaration. They look like this: 


[mame], ID [ (attributes) } 
type-specific resource data 


Note that the comma separating the name from the ID must be included even if you don’t 
name the resource. The attributes byte must be surrounded by parentheses. See the Inside 
Macintosh I, Chapter 5, “The Resource Manager” to learn more about resource attributes. 


A blank line must follow the resource definition. 


Predefined Resource Types 


RMaker recognizes these 12 resource types. 


"ALRT' - Alert 

‘BNDL' - Bundle 

"CNTL’ — Control 

'DITL' - Dialog (or Alert) Item List 
'DLOG' - Dialog 

'FREF' - File Reference 

'GNRL' - General 

"MENU' - Menu 

'PROC' - Procedure (contains code) 
"STR ' = String 

'STR#' - String List 

‘WIND' - Window 


The following sections illustrate the different types of resource declarations: 
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TYPE ALRT 
x 128 


70 100 150 412 


10 
FEFF 


77 the resource number 
77 xvectangle for the alert (top left bottom right) 
77 the resource ID for the item list 


77 stages w 


ord (hex) 


* always remember the blank line at the end of a resource 
* definition - it is a required separator 


"BNDL' - Bundle Template for Application 


TYPE BNDL 
7128 

SAMP 0 

ICN# 

0 128 1 129 

FREF 

0 128 1 129 


; 


; 


resource number 


creator for 
resource typ 


resource typ 


‘CNTL' - Control Template 


TYPE CNTL 
7128 

MyControl 

10 10 20 20 

Visible 

0 

0 

0 100 0 


bundle 


e (icon list) 

local ID 0 maps to ICN# resource 128, 1 to 129 
e (file reference) 

local to FREF mapping 0 to 128, 1 to 129 


resource number 


title for co 
rectangle fo 
may also be 
CDEF proc ID 
reference co 
minimum valu 


‘DITL' - Dialog (or Alert) Item List 


TYPE DITL 
Pees) 
9 


button 
20 20 40 100 
Cancel 


radioButton 
50 20 70 120 
Push Me 


radioButton disabled ii 


50 20 70 120 


ntrol 
r control 
Invisible 


(top left bottom right) 


nstant (defines control type) 
e, maximum value, initial value 


resource number 
number of items in the item list 


enabled button items (enabled by default) 


rectangle 


(window-relative coordinates) 


text in the button 


radio button item 


rectangle 


(includes button and text) 


the text goes to the right of the button 


dimmed radio button item 


rectangle 


(includes button and text) 
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Can't Push Me 7# you can't push a disabled button 
checkBox 77 check box item 

80 20 100 120 77 rectangle (includes check box and text) 
Check Me 7; the text goes to the right of the box 
staticText 77 static text item 

20 120 40 320 77 rect of text 

This text would get placed next to the Cancel button ;; the text 
editText Disabled 7; Gisabled editable text item 

50 140 90 320 +7 rect of the box for editable test 
initial string 77 initial edit text 

editText +; editable text item (enabled by default) 
100 140 120 320 77 rectangle 

you can edit this text ;; the initial string for editable item 
iconItem +; for the display of an icon 

100 100 132 132 77 vectangle should be 32x32 

is 77 resource ID for icon (Type ICON) 
picItem 7; to display a Quickdraw picture 

30 100 20 200 7; display rectangle (picture will be scaled) 
57 +; resource ID for picture (Type PICT) 
useriItem +7 a user-defined item 

30 40 80 90 7; the rectangle 


'DLOG' - Dialog Template 


TYPE DLOG 
7128 7; the resource number 
My Dialog Box 77 a message 
70 100 150 412 7; the rectangle (top left bottom right) 
Visible NoGoAway 77 ox Invisible or GoAway 
oO 77 the dialog definition ID 
0 7; the refCon, available to the user 
10 7; the resource ID for the dialog item list 


"FREF' - File Reference 


TYPE FREF 
,128 77 the resource number 
APPL 0 77 the file type and local ID 
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‘GNRL' - General 


'GNRL' is used to define your own resource types and to define their format. The resource’s 
format is constructed from “elements.” The elements available are: 


Pascal string 


Decimal integer 


BREW 


Decimal 32-bit integer 
Hexadecimal integer 
Read the given resource from the given file 


String without a leading length byte 


R takes the arguments filename resource TYPE resource ID 


TYPE ICN# = GNRL 
7128 

-H 

0001 8000 0002 4000 

0003 C000 0004 2000 


PFFF FFFF FFFF FEFF 


‘MENU’ - Menu 


TYPE MENU 

710 
MyMenu 
First Item 
Second Item /S 
(Third Item 
(- 
Fifth Item 


define the type ICN# 

the resource ID 

hexadecimal data follows 

ICN#'s need 2 icons (icon and 
mask) of 32x32 bits each, or 32 
lines of two longwords apiece. 


the resource number (Menu ID) 

the menu title 

the first menu item 

the second menu item with Command-S 
the third item — “(” disables items 
a gray line (this is item #4) 

the fifth item 


‘PROC’ - Procedure (contains code) 


TYPE PROC 
7128 
Filename 


"STR '- String 


TYPE STR 
,128 
My Wild Irish Rose 


the resource number 
the code from this file will get placed 
in the resource 


spelled 'STR ' - trailing space required! 
the resource number 
the string assigned to the resource 128 
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"STR#' - String List 


TYPE STR# 
,128 7; the resource number 
2 7; the number of strings in the list 
The First String 
And the second string 77 the two strings in the list 


‘WIND’ - Window 


TYPE WIND 
7128 77 the resource ID 
My Window 77 the window title 
40 40 200 472 77 the window rect (top left bottom right) 
Visible GoAway 77 or Invisible or NoGoAway 
0 77 the window definition ID 
0 73 xvefCon, a long word available to user 


379. 


Error Messages 
E 


This appendix is a guide to the error messages THINK Pascal generates. Compile, link, and 
the common runtime error messages, with their explanations, are arranged in alphabetical 
order. There are cross references to other chapters in this manual and examples of incorrect 
and correct code fragments. 


Error messages appear in an alert box, unless an error occurs while evaluating an expression 
in the Observe window. In that case, an abbreviated error message appears in the left cell of 
the Observe window. 


The examples have also taken advantage of THINK Pascal’s relaxation of order and number 
of declarations in a block. 


The examples assume that the following constants, types, and variables are defined:: 


const 
aConstant = 42; 
aCharConstant = 'c'; 
aStringConstant = 'hi there'; 
type 
ColorType = (red, orange, yellow, green, blue, violet); 


WeightType = (LIGHT, MEDIUM, HEAVY); 
aType = integer; 
var 
aBool : boolean; 
aChar : char; 
anInt : integer; 
aLong : longint; 
aReal : real; 
aDouble : double; 
anExt : extended; 
aString : string; 
aColor : ColorType; 
aPtr : Ptr; { Ptr is a predefined type } 
{ that points to SignedByte } 
ColorSet : set of ColorType; 
TextFile : Text; 
FileOfInt : file of integer; 
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“symbol” is already declared at this level. 
See 2.2.4 of Chapter 17. Example: 


var 
aDupName : integer; 
aDupName : real; { Error: aDupName already declared } 
type 
recordType = record 
aDupName : integer; { OK:first time in the record } 
aDupName : real; { Error: already declared in record } 
end; 
procedure aDupName; { Error: already declared as a variable } 
begin 
end; 
procedure Pl (aDupName:char); { OK: aDupName is not declared } 
{ at this level } 
begin 
end; 
procedure P2 (X:char; X:real); { Error: X declared twice } 
{ in parameter list } 
begin 
end; 


“symbol” is not declared. 


* Check your spelling. Be careful to distinguish between 1 (one), | (lower case L), and 
I (upper case i); and between 0 (zero) and O (oh). (Pascal is not case sensitive.) 

e Make sure the symbol is declared before it is used. 

¢ Make sure the symbol is visible at the level you are trying to use it. 

* Ifthe symbol is in another unit, don't forget to use the unit name ina uses clause. 


In almost all cases, a name must be defined (or predefined) before it can be used. See 
Sections 3, 4, and 7 of Chapter 17. Example: 


program HasUndeclaredSymbols; 
type 
BadType = TypeYet ToBeDefined; 
TypeYetToBeDefined = integer; 


{ Error } 

{ This must come before } 

{ the previous statement } 
RecPtrType = *RecType; { OK: a pointer type to a } 
{ type to be defined later } 
RecType = record 

PtrToARecord : *“UndefinedType; { Error } 


PtrToNextRecord : RecPtrType; { OK } 
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aField : integer; 
end; 


var 
xr : RecType; 
procedure Proc; 


var 
PrivateToProc : integer; 
begin 
end; 
begin 
PrivateToProc := 4; { Error: PrivateToProc isn't } 
{ declared at this level } 
aField := 4; { Wrong } 
r.aField := 4; { Right } 
UndeclaredVariable := 4; { Error } 
UndeclaredProcedure; { Error } 
r.aField := UndeclaredFunc; { Error } 


end. 


“symbol” isn't in the current project, hasn't been successfully compiled, or is in 
the wrong build order. 

When you use a unit, the unit must be compiled in the project. The unit being used must 
appear before the units that use when you see the project by build order. See Chapter 7 and 
§8.5 of Chapter 17. Example: 


unit anUnit; 
interface 
uses 
NonExistantUnit, UncompiledUnit, UnitFollowingThisOne; 
{ Error } 
implementation 
end. 


“symbol” looks like it's being used as a function, but it isn't a function name. 
See 5.2 of Chapter 17. Example: 


program test; 


const 
x= 5; 
var 
i: integer; 
begin 
i:= x; { Correct } 
2% 32. 2Ce { ERROR } 
end; 
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“symbol” looks like it's being used as a procedure, but it isn't a procedure name. 
See 6.1.2 of Chapter 17. Example: 


type 

IntPtrType = “integer; 
var 

anIntPtr : IntPtrType; 


function Func : char; 


begin 

end; 
begin 

aChar; { Error } 

aChar := Func; { Right } 

anIntPtr := pointer(aPtr); { See §10.2.6 of Chapter 17 } 

anIntPtr*® := 3 { Right: use temp variable anIntPtr } 
end; 


“symbol” was previously declared as a function, not a procedure. 


When a function is declared in an interface part or as a forward function, it cannot be 
defined later as a procedure. See 7.1.1 and 8.1 of Chapter 17. Example: 


unit MisdefinedFunctions; 
interface 
function InterfaceFunc : char; { To be defined in IMPLEMENTATION } 
implementation 
procedure InterfaceFunc; { Wrong: FUNCTION declaration expected } 
begin 
end; 
function InterfaceFunc; { Right } 
begin 
end; 
function ForwardFunc : char; { To be defined below } 
forward; 
procedure ForwardFunc; { Wrong: FUNCTION declaration expected } 
begin 
end; 
function ForwardFunc; { Right } 
begin 
end; 
end. 
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“symbol” was previously declared as a procedure, not a function. 


When a procedure is declared in an interface part or as a forward procedure, it cannot 
be defined later as a function. See 7.1.1 and 8.1 of Chapter 17. Example: 


unit MisdefinedProcedures; 


interface 
procedure InterfaceProc; { To Be defined in IMPLEMENTATION part } 
implementation 
function InterfaceProc : char; { Wrong: PROCEDURE definition } 
{ expected } 
begin 
end; 
procedure InterfaceProc; { Right } 
begin 
end; 
procedure ForwardProc; { To Be defined below } 
forward; 
function ForwardProc : char; { Wrong: PROCEDURE definition } 
{ expected } 
begin 
end; 
procedure ForwardProc; { Right } 
begin 
end; 
end. 


@ can only be applied to variable references, or to top-level procedure or function 
names. 

The address operator @ can only be applied to objects that actually have memory allocated to 
them. For example, constants, types, etc., do not allocate memory. Furthermore, @ cannot be 
applied to sub-level subroutines, because references to the variables in the outer scope 
cannot be set up properly. See 5.1.6 and 5.1.6.4 of Chapter 17. Example: 


program AtSigns; 
procedure Proc; 
procedure SubProc; 


begin 
aPtr := @Proc; { OK } 
aPtr := @SubProc; { Error: SubProc is not } 
{ a top level procedure } 
end; 
begin ( Proc } 
end; 
begin 
aPtr := @anInt; { OK: memory is allocated for anInt } 
aPtr := @Proc; { OK } 
aPtr := @aConstant; { Error: aConstant is a constant } 
aPtr := @orange; { Error: orange is an enumerated constant } 
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aPtr := @ColorType; { Error: ColorType is a type } 
aPtr := @integer; { Error: integer is a type } 
end. 


@ can't be applied to a component of a packed type. 


@ cannot be applied to components of packed structures, because the actual data 
representation of a component in a packed structure may be different from that actual data 
representation in an unpacked structure. However, @ can be applied to the packed structure 
as a whole. See 5.1.6.2 of Chapter 17. 


@ can't be applied to predefined or inline routines. 

The @ operator can only be applied to actual routines, not predefined, inline, or Macintosh 
Toolbox routines (which don't generate real subroutine calls). However, you can write a 
wrapper routine which wraps itself around the desired routine. Then, the @ operator can be 
applied to that wrapper. See 5.1.6.4 of Chapter 17, Example: 


procedure NOP; 


inline 
$4e71; { M68000 NOP instruction } 
procedure WritelnWrap (s : string); 
begin 
writeln(s); 
end; 
procedure NOPWrap; 
begin 
NOP; 
and; 
function ButtonWrap : boolean; 
begin 
ButtonWrap := Button; 
end; 
begin 
aPtr @writeln; { Wrong: writeln is predefined procedure } 
aPtr @writelnWrap; { Right: writeln is in a wrap routine 
aPtr @NOP ; { Wrong: NOP is an inline procedure } 
aPtr @NOPWrap; { Right: NOP is in a wrap routine } 
aPtr @Button; { Wrong: Button is an Toolbox routine } 
aPtr := @ButtonWrap; { Right: Button is in a wrap routine } 
end. 


Array index type incompatibility. 


The type of the expression that indexes an array must be compatible with the type of the 
index in the array declaration. See 4.3.1 of Chapter 17. Example: 


var 
ai : array[1..10] of char; 
aC : array[ColorType] of char; 


Error Messages = 


begin 
ail[4]:='a'; 
ai(4 + anInt]):='a'; 


{ OK: 4 is within 1..10 } 

{ OK: type of (4+tanInt) is } 

{ compatible with 1..10 } 

aifaReal]:='x'; { Wrong } 

ai[round(aReal) ]:='x'; { Right } 

ai[aColor]:='x'; { Wrong } 

aiford(aColor)]:='x'; { Right: but why bypass strong typing? } 

aC[aColor]:='x'; { Right: Best } 

ai [Ne J cmtagts { Error } 

ai[4 + aReal]:='x'; { Error: type of 4+aReal is Real, not 1..10 } 

ai[succ(aColor) ]:='x'; { Error: succ(aColor) is ColorType } 

aifaif[anInt]]:='x'; { Error: aifanInt] is char, not 1..10 } 

aChar:=aString[aChar]; { Wrong: string index must be 1..255 } 
aChar:=aString[ord(aChar)]; { Right } 

end; 


Array index type is not integer, char, enumerated, or subrange. 
See 3.2.1 of Chapter 17. Example: 


var 
Good_1 array['A'..'Z') of char; { OK: char subrange } 
Good_2 array(ColorType] of char; { OK: enumerated type } 
Good_3 : array[1..10] of char; { OK: integer subrange } 
Bad_1 : array[real] of char; { Error } 


Assignment type incompatibility. 

You can’t put a square peg in a round hole. Pascal catches illogical statements that try to 
assign an expression of one type into a variable of an assignment-incompatible type. On 
occasion, this rule needs to be broken. The following examples show common errors and 
methods to break the rules. Use the methods at your own risk. Assignment compatibility can 
be subule. See 3.5.3 and 5.4 of Chapter 17. Example: 


type 
CanonicalType = array[1..4] of char; { a type } 
IdenticalType = CanonicalType; { identical to CanonicalType 
AnotherType = array[1..4] of char; { a type DIFFERENT from } 
{ CanonicalType } 
var 


AnonArray : array[1..4] of char; { an array of anonymous type } 
CanonicalArray : CanonicalType; { a variable of a named type } 
IdenticalArray : IdenticalType; { a variable of a same type } 
AnotherArray : AnotherType; { a variable of a different } 
{ named type } 

AC : array[1..4] of char; 
PAC : packed array[1..4] of char; 
Rec : packed record 

i: integer; 

end; 
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pint : “integer; 
pChar : “char; 
begin 
aString:=AC; { Wrong: can't assign UNpacked array of char } 
{ to strings } 
aString:=PAC; { Right: OK to assign pack array of char to strings } 
PAC:=aString; { Right: OK to assign strings to pack array of char } 
AC:=PAC; { Error: can't. assign packed to unpacked array } 
Real; { Wrong: Pascal doesn't convert float to integer } 
ound(aReal); { Right: explicit conversion } 
runc(aReal); { Right } 
{ OK: Pascal converts integer to float } 
{ OK } 
{ OK } 
{ Wrong: can't assign enumerated type to integer } 
ord(green); { Right: but why bypass strong typing? } 
aColor:= anInt; { Wrong: can't assign integer to enumerated } 
aColor:=ColorType(anInt); { Right: a CAST works but why } 
{ bypass strong typing? } 
AC:=Rec; { Error: can't assign totally different types } 
pint :=pChar; { Wrong: can't assign different pointer types } 
piInt:=pointer(pChar); { Right: a CAST works but why } 
{ bypass strong typing? } 


pint := 7; { Wrong: can't assign a pointer a numerical value } 
pInt* := 7; { Right } 
CanonicalArray := IdenticalArray; { OK } 
CanonicalArray := AnotherArray; { Error: the types aren't } 
{ assignment compatible } 
CanonicalArray := AnonArray; { Error: anonymous types are never } 
{ assignment compatible } 
end; 
At A-Trap 


This runtime message appears in the Observe window when the Break At A-Traps 
command is checked, and the expression being observed, directly or indirectly, calls a 
Macintosh Toolbox routine. See Chapter 14. 


At least one comment of more than 255 characters has been truncated to 255. 
THINK Pascal only supports comment lines which have fewer than 256 characters. 


At least one identifier, literal string, or other token of more than 255 characters has 
been truncated to 255. 


THINK Pascal only supports identifiers, string literals, and other tokens which have fewer 
than 256 characters. 
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At least one valid constant declaration must follow CONST. 
See 1.7 and 2.1 of Chapter 17. Example: 


const 
BadConstant : false; { Wrong: Colon(:) instead of Equal(=) } 
GoodConstant = true; { Right } 
const 
{ Error: must have at least one CONST declaration } 
begin 
end; 


At least one valid type declaration must follow TYPE. 
See 2.1 and 3 of Chapter 17, Example: 


type 
BadType : integer; { Wrong: Colon(:) instead of Equal(=) } 
GoodType = integer; { Right } 
type 
{ Error: must have at least one TYPE declaration } 
begin 
end; 


At least one valid variable declaration must follow VAR. 
See 2.1 and 4.1 of Chapter 17. 


var 
BadVariable = integer; { Wrong: = instead of : } 
GoodVariable : integer; { Right } 
var 
{ Error: must have at least one VAR declaration } 
begin 
end; 


Autointerrupt exception 

This runtime message is given when the programmer's switch is hit, but a low level debuger 
(Macsbug or TMON) is not installed. This should only be used as a last resort. Since you 
cannot be sure of the state of your program, it may crash if you restart or reset it. Therefore, 
save all your files before continuing. It’s better to run with code compiled with the Debug 
Option (see Chapter 15) and click on the Bug Spray Can to stop, or always have a low level 
debugger installed. 


Available memory for variables declared at this level has been exhausted. 


Because of the MC68000 architecture, the local storage per function or procedure must not 
exceed 32766 bytes. Similarily, the total global storage must not exceed 32766 bytes. 
Excessive global storage may not be detected until link time. 
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In practice, even less storage may be available. Subroutines require local storage for all 
temporary variables generated by the compiler. For applications, QuickDraw globals are 
included in global storage. Furthermore, libraries may also require some global storage. 


If you need more memory, you must use storage allocation subroutines. See 10.1 and 10.2 of 
Chapter 17. For large data structures, the use of handles is highly recommended. See Inside 
Macintosh. THINK Pascal lets you decalre types that are bigger than 32K, so it’s easy to use 
the Memory Manager to get huge arrays. 


program MemoryHog; 
const 
HalfTooBig = 16500; { The Max global size is about 32000 bytes } 
TooBig = 33000; 
type 
BigArrayType = packed array[0..HalfTooBig] of char; 
HugeArray = packed array [0..TooBig] of char; { OK } 
HugePtr = *TooBigArrayType; 
HugeHandle = “TooBigArrayTypePtr; 


var 
BigGlobalArrayl : BigArrayType; { OK } 
BigGlobalArray2 : BigArrayType; { Error : Too much memory } 


{ Better: } 
BigArrayPtrl : “BigArrayType; { Allocate Pointers instead 
BigArrayPtr2 : *“BigArrayType; 
TooBigArray : HugeArray; {Error: Way too big } 
{ Much Better} 
hTooBigArray : TooBogArrayTypeHandle { OK } 
procedure aProc; 
var 
BigLocalArrayl : packed array[0..HalfTooBig] of char; { OK } 
BigLocalArray2 : packed array[0..HalfTooBig] of char; { Error } 


begin 
end; 
begin 
New (BigArrayPtrl); { Allocate memory } 
New (BigArrayPtr2) ; 
BigArrayPtr1%*[15000] := ‘c'; { Can access large array } 
{with pointers } 
hTooBigArray := HugeHandle (NewHandle (sizeof (HugeArray))); { OK } 
hTooBigArray**[33000] := 'z'; 
end. 


Bad actual parameter for formal VAR, procedural, or functional parameter. 
See sections 7.3.2, 7.3.3, and 7.3.4 of Chapter 17. Example: 


procedure VarProc (var i : integer); 
begin 
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end; 
procedure Proc (i : integer); 
begin 
end; 
procedure CallP ( procedure P (i : integer)); 
begin 
end; 
function Func (c : char) : char; 
begin 
end; 
procedure CallF ( function F (c : char) : char); 
begin 
end; 
begin 
VarProc(anInt + 4); Error: expressions can't be passed } 
as VAR parameters } 
OK } 
Wrong: procedural parameters aren't } 
called with parameters } 
Right } 
Wrong: functional parameters aren't ) 
called with parameters } 
Right } 


VarProc(anInt) ; 
CallP (Proc (3)); 


CallP (Proc) ; 
CallF (Func('c')); 


CallF (Func) ; 
end; 


Bad compiler directive 
You probably forgot something in a compiler directive 


program test; 


begin 

{$SETC compiler_var = false} { Correct } 

{$IFC compiler var} { Correct } 

writeln('This line will not be compiled.'); 

{ SENDC} 

{$IFC} { ERROR: missing expression } 
{ $SETC} { ERROR: missing assignment } 
end. 


Bad decimal-places expression in WRITE, WRITELN, or STRINGOF call. 

The decimal-places expression is only valid for real output expressions and must evaluate to 
a positive integer expression. See 9.4.3.1, 9.4.3.2, 9.4.3.3, 9.4.3.4, 9.4.3.5, 9.4.3.6, and 9.4.3.7 
of Chapter 17. Example: 


writeln(anInt : 7 : 3); { Error } 
writeln(aString : 7: 3); { Error } 
writeln(aReal : 7 : aString); { Error } 
aString := stringof(anInt : 7 : 3); { Error } 
aString := stringof(aString : 7 : 3); { Error } 
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Bad enumerated value. 


During runtime, the procedure read, readln, or readstring expected an enumerated 
value for a specific type, but did not get one. See 9.4.1.5 of Chapter 17. Example: 


readstring('paisley', aColor); { Error } 
readstring('plaid', aColor); { Error } 
readstring('violet', aColor); { OK } 
readstring('yeLLOW', aColor) ; { OK: case not important } 


Bad expression type for READSTRING, or for READ or READLN from a text file. 


Text files and strings can only contain characters. Values that have a string representation 
(except for packed arrays of characters) can be read from a text file or extracted from a string. 
For example, an integer can be represented by a string of digits and can be read from a text 
file. On the other hand, a record cannot be read from a text file, because it is a collection of 
data which does not have a simple string representation. You might think it should be 
represented in a particular string format, but there are no rules for it in Pascal. 


Values that cannot be read from a text file, can be read from a file of that value's type. For 
example, an entire record can be read froma file of that record's type. If you really want 
to read a record from a text file or a string, then read each field of the record from the file or 
from string. See 9.4.1, 9.4.2, and 10.7.6 of Chapter 17. Example: 


type 
RecType = record 
Field_1 : integer; 


Field 2 char; 
end; 
var 
InString : string; { Input String that readstring reads from } 
TextFile : text; { Input that readin reads from } 


FileOfREC : file of RecType; 
IntPtr : “integer; 
anArray : array[1..2] of char; 
PAC : packed array[1..6] of char; 
Rec : RecType; 
begin 
open(TextFile, ‘text file'); 
open (FileOfREC, 'file of records'); 
readin (TextFile, aChar, aString, aColor, anInt, aLong, aReal); {OK} 


readln(TextFile, IntPtr); { Wrong } 

readin (TextFile, aLong); { OK, but probably not } 
IntPtr := pointer (aLong) ; { what you really want to do } 
readln(TextFile, IntPtr*%); { Right } 

readin (TextFile, anArray); { Wrong } 


readin (TextFile, anArray[1], anArray[2] ); { Right } 

readln(TextFile, Rec); { Wrong: can't read a record } 
{ from a text file } 

readin (FileOfREC, Rec); { Wrong: can't input a record } 
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{ with a readin } 


read(FileOfREC, Rec); { Right: OK to read a record } 


{ from a file of records } 


readin (TextFile,Rec.Field_1,Rec.Field 2); { Right: OK to read } 


{ fields from TextFile } 


readstring(InString, aChar, aString, aColor, anInt, aLong, aReal); 


{OK} 
readstring(InString, anArray) ; { Error } 
readstring(InString, Rec); { Error } 


end; 


Bad expression type for STRINGOF, or for WRITE or WRITELN to a text file. 

Text files can only contain characters . Values that have a string representation can be written 
to a text file or copied to a string. For example, an integer can be represented by a string of 
digits and can be written to a text file. On the other hand, a record cannot be read from a text 
file because it is a collection of data that does not have a simple string representation. You 
might think it should be represented in a particular string format, but there are no rules for it 


in Pascal. 


Values that cannot be written out to a text file can be written out toa file of that value's 
type. For example, a record can be written toa file of that record's type. If you really 
want to write a record to a text file, then write each field of the record to the text file or copy 
each field to a string. See 9.4.3, 9.4.4, and 10.7.5 of Chapter 17. Example: 


type 
RecType = record 
Field 1 : integer; 
Field 2 2: char; 
end; 
var 


IntPtr : “integer; 
anArray : array[1. 


-2]) of char; 


PAC : packed array[1..6] of char; 


aRec : RecType; 


FileOfREC : file of RecType; 


Result : string; 
begin 


open(TextFile, 'text file'); 
open(FileOfREC, ‘file of records'); 


writeln (TextFile, 


aBool, aChar, aString, aColor, 


anInt, aLong, aReal, PAC); {OK} 
Result := stringof(aBool, aChar, aString, aColor, 
anInt, aLong, aReal, PAC); {OK} 


writeln (TextFile, 
writeln (TextFile, 


writeln (TextFile, 
writeln (TextFile, 


ord4 (IntPtr) ); { OK, probably not what } 

{ you really want to do } 

IntPtr®); { Right: outputs what IntPtr } 
{ points to } 

anArray); { Wrong } 

anArray[1], anArray[2]); { Right } 
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write(TextFile, aRec); { Wrong: can't write a record } 
{ to a Text file } 
writeln(FileOfREC, aRec); { Wrong: can't output a record } 
{ with a writeln } 
write(FileOfREC, aRec); { Right: OK to write a record } 
{ to a file of records } 
write (TextFile, aRec.Field 1, aRec.Field 2 ); { Also Right } 
writeln (ColorSet) ; { Wrong: can't write out a set directly } 
{ Right: find elements in set and print them } 
for aColor := red to violet do 
if aColor in ColorSet then 
write (aColor) ; 


Result := stringof (anArray) ; { Error } 

Result stringof (TextFile) ; { Error } 

Result := stringof (aRec) ; { Error } 
end; 


Bad field-width expression in WRITE, WRITELN, or STRINGOF call. 

The field-width expression must evaluate to an integer expression greater than 0. Also, it is 
forbidden to use field widths when writing to non-text files. See 9.4.3.1, 9.4.3.2, 9.4.3.3, 
9.4.3.4, 9.4.3.5, 9.4.3.6, and 9.4.3.7 of Chapter 17. Example: 


anInt := 7; 
writeln(anInt 
writeln(anInt 


1 + anInt); 
aString) ; 


{ OK } 

{ Error: field width expression } 
{ must be an integer } 

{ Error: field width expression } 
{ must be an integer } 


writeln(anInt : aReal); 


aString := stringof(anInt : aString); { Error } 

aString := stringof(anInt : aReal); { Error } 

write(FileOfInt, anInt : 4); { Wrong: can't specify field } 
{ width for non-text files } 

write (FileOfInt, anInt); { Right } 


Bad integer value. 


When reading a value from a text file into a variable, if the text cannot be converted to a 
value for the variable type, then this runtime error occurs. See 9.4.1, 9.4.1.1, 9.4.1.2, 9.4.1.3, 
9.4.1.4,, 9.4.1.5, and 9.4.2 of Chapter 17. 


reset (TextFile, 'file containing ONLY letters'); 
readln(TextFile, anInt); { Error: can't convert letters into integers } 
readin(TextFile, aString); { OK: any ASCII text can go into a string } 


Bad object type in method declaration 
The object type modifier in a method declaration is not an object name. 
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program test; 
uses 
ObjIntf; 
type 
T = integer; 
procedure T.x; { ERROR: 'T' is not an object type } 
begin 
end; 


begin 
end. 


Bad pointer in DISPOSE. 


This runtime error most frequently occurs when you try to dispose an uninitialized or nil 
pointer or when you try to dispose the same memory twice. A less likely cause is that the 
heap is corrupted. This can happen if memory is used after it has been disposed. Use 
pointers with care. See 10,1.2 of Chapter 17. 


Bad real value. 
Your program attempted to read in a real value but found non-real characters instead. 


program test; 


var 
x: real; 
textfile: text; 
begin 


reset (textfile, '‘reals'); 
while not eof(textfile) do 
readln(textfile, x); { ERROR when 'wxyz' is read } 
close (textfile) ; 
end. 


contents of file 'reals': 


Bad set constructor. 
See 5.3 of Chapter 17. 


ColorSet := [[]]; { Wrong: can't have a set of an empty set } 
ColorSet := []; { Right: Empty Set } 
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Bad SIZEOF parameter. 


The predefined function sizeof can only take variable or type names. (Note: the size of a 
string is not the same as its length, see 3.3 and 4.3.1 of Chapter 17). sizeof is described in 
10.7.1 of Chapter 17. Example: 


type 
LongType = longint; { sizeof = 4 } 
var 
size : integer; 
stringl9 : string[19]; 
string20 : string[20]; 
pr2 : packed record { sizeof 
cl, c2 : char; 
end; 
pr3 : packed record { sizeof = 4 : extra byte to align even word } 
ex), io2; eS 4: chan 


2 : packed chars are 1 byte apiece } 


end; 

ur2 : record { sizeof = 4 : unpacked chars take up 2 bytes apiece } 
el; 2. = char? 

end; 


arrayl0 : array[1..10] of integer; 
procedure aProcedure; 
begin 
end; 
function aFunction : boolean; 
begin 
end; 
begin 
size := sizeof(anInt + aLong); { Error: sizeof doesn't work } 
{ with expressions } 


size := sizeof(aProcedure); { Error: sizeof doesn't work } 
{ with procedures } 

size := sizeof (aFunction); { Error: sizeof doesn't work } 
{ with functions } 

size := sizeof (aConstant); { Error: sizeof doesn't work } 


{ with constants } 


size := sizeof (pr2.cl); { Error: sizeof doesn't work } 
{ with record components } 
size := sizeof(arrayl0[1]); { Error: sizeof doesn't work } 
{ with array elements } 
size sizeof (LongType) ; { OK: size = 4 } 
{ 
{ 


size sizeof (stringl9) ; OK: size = 20 } 
size := sizeof (string20) ; OK: size = 22 } 
{ 1 len + 20 data + 1 padbyte } 

size sizeof (pr2) ; { OK: size = 2 } 
size sizeof (pr3) ; { OK: size = 4 } 

{ pad byte to align even word } 
size := sizeof (ur2); { OK: size = 4 unpacked chars } 

{ take up 2 bytes apiece } 
size sizeof (arrayl0) ; { OK: size = 20 } 
size sizeof (size); { OK: size = 2 } 
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size := sizeof (boolean) ; { OK: size = 1 } 
size := sizeof(char); { OK: size = 2, unpacked chars } 
{ take up two bytes } 
sizeof (integer) ; { OK: size = 2 } 
sizeof (longint) ; { OK: size = 4 } 
sizeof (real); { OK: size = 4 } 
sizeof (double) ; { OK: size = 8 } 


sizeof (extended); { OK: size = 10 } 


Boolean expression required. 


Boolean expressions are required in control statements and with boolean operators. See 
6.2.2.1, 6.2.3.1, 6.2.3.2, 5, and 5.1.3 of Chapter 17. Example: 


aBool := 3 or 4; { Error: the numbers 3 and 4 aren't booleans } 
if 3 + 4 then { Error: (3+4) doesn't evaluate to True or False } 
repeat 
until aReal; { Error: aReal doesn't evaluate to True or False } 


while green do { Error: green doesn't evaluate to True or False } 


; 


Can’t convert .o file 


The MPW object file that THINK Pascal is trying to load contains some contructs that THINK 
Pascal can’t convert to its format. For instance, THINK Pascal cannot use MPW object files 
that contain computed references or intialized data. 


Can't EXIT procedure "procedure_name" from here 
The procedure name in an Exit statement must enclose the statement. 


program test; 
procedure proc; 
begin 
showtext; 
writeln('This will be written’); 
exit (proc) ; { CORRECT } 
writeln('This will not be written'); 
end; 
begin 
proc; 
exit (proc); { ERROR: "proc" does not enclose this statement } 
end. 


Can't find the file “filename”. Would you like to look for it? 

THINK Pascal remembers where a project's files are by pathname. When this dialog box 
appears, the file is no longer where the project thinks it is. Either you have deleted the file or 
you have moved it to a new location. If you click OK and find the file, the project will 
remember its new location and ask you: 
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Change “old location” to “new location” in all SUBSEQUENT (by build order) 
Project entries also? 


THINK Pascal thinks if you have moved one file, so it is likely that you have moved other 
files too. As a convenience, you can change the references from the old location to the new 
location, but only by build order starting with files after the one you just changed. 


Can't read Keyboard or Modem. 


This runtime error occurs when an expression in the Observe window ties to get input from 
the keyboard or modem. For example, the value cell of the Observe window will display this 
error when evaluating either of the following functions: 


var 
s : string; 
fe Heke + 
function ReadKeyBoard : integer; 
begin 
readin (s); 
ReadKeyboard := length(s); 
end; 
function ReadModem : integer; 
begin 


reset (f, 'MODEM:') ; 
readin (f, s); 
ReadModem := length(s) ; 
close (f); 
end; 


Case constant incompatible with tag-type or selector expression. 
See 3.2.2 and 6.2.2.2 of Chapter 17. Example: 


type 
BadVariantRecordType = record 
case Tag : ColorType of 
red : ( { OK: red is a ColorType } 
i: integer; 


LS! ie: { Error: 15 is not a ColorType } 


j : real; 
3 
end; 
begin 
case aColor of 
red : { OK: red is a ColorType } 
writeln('OK'); 
15. 8 { Error: 15 is not a ColorType } 


writeln('Error'); 
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end 
end; 


Case constant needed here. 
See 6.2.2.2 of Chapter 17, Example: 


var 
aVariantRecord : record 
case boolean of 
: ( { Wrong: missing case constant before the colon (:) } 


i: integer 
de 
true : ( { Right: true is a valid case constant } 
e : char 
; 
end; 
begin 


case anInt of 


writeln('Wrong: missing case constant before colon (:)'); 


3 8 

writeln('Right: 2 is a vaild case constant'); 
34.6.5 

writeln('Right: Subranges in Case List allowed '); 
Bie Me, Bian Gr cz 

writeln('Right: 3,4,5,6 are valid case constants'); 
end; { of case } 


case anInt of 


{ Error: at least one case constant required } 
end; { of empty case } 
end; 


Change “old location ” to “new location ” in all SUBSEQUENT (by build order) 
Project entries also?“ 


See the error message: 
“Can't find the file 'filename'. Would you like to look for it?“ 


Colon (:) required on this line or above. 


Colons are needed in labeled statements and case statements. See 3.2.2, 6.1.3, and 6.2.2.2 of 
Chapter 17. Example: 


procedure Proc; 
label 
1, 23 
begin 
goto 1; 
1 { Wrong: missing colon after the label 1 } 
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writeln; 
goto 2; 
ey { Right } 
writeln; 
end; 
end; 


Compiler variable is not defined 
Before you can use a compiler variable ina {$IFC} directive, you must define it. 


program test; 

{$SETC defined_var = false) { Definition of ‘defined var' } 
{$IFC defined_var} { Correct } 

{ $ENDC} 

{$IFC undefined_var) { ERROR: 'undefined_var' is not defined } 
{ SENDC} 

begin 

end. 


Component type of a file can't contain a file type. 
See 3.2.4 of Chapter 17. Example: 


type 
FileType = file of integer; 
Bad_NestedFileType = file of FileType; { Error: FILE OF a } 


{ file type } 
Bad_NestedFileRecordType = file of record 
F ; FileType; { Error: FILE OF a type containing file } 
end; 
Bad_FileOfText = file of Text; { Error: Text is a file type } 


Constant expected. “symbol” isn't a constant. 


At the erroneous statement, the compiler needs a constant to generate code for storage 
allocation, case statements, or variant records. See section 3 and 6.2.2.2 of Chapter 17. 


Example: 
var 
NotAConstant : integer; 
aBadString : string[NotAConstant]; { Wrong } 
aGoodString : string[aConstant]; { Right } 
Bad : array[1..NotAConstant] of char; { Wrong } 
Good : array[1l..aConstant] of char; { Right } 
begin 
case anint of 
NotAConstant : { Wrong: case tags must be constants } 
writeln('Equal to NotAConstant') ; 
aConstant : { Right: this case tags is constants } 


writeln('Equal to aConstant'); 
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otherwise 
writeln('Otherwise something else') 
end; 
{ If you really want to have variable case tags, } 
{ use a series of else-ifs } 


if anInt = NotAConstant then { Right } 
writeln('Equal to NotAConstant') 
else if anInt - aConstant then { Right } 
writeln('Equal to aConstant') 
else 
writeln('Otherwise something else') { Right } 
end; 


Constant or expression (whose ordinal value is Value) is out of range. 
This compile time error is detected only when the Range compiler directive is on. See 
Chapter 15. Example: 


var 
a: array[1..10] of 1..6; 
£ weal} 


SmallInt : 1..10; 
Cool : green..violet; 


Cool := red; Error: red is out of range for Cool. } 


ord(red) = 0 } 


begin 
Smallint H 8 BE { Error: 11 is too big for SmallInt } 
Smallint 0; { Error: 0 is too small for SmallInt } 
SmalliInt 5 + 6; { Error: 11 is too big for Smallint } 
a[ll1)} { Error: 11 is out of range for Index } 
a[10] { Error: 7 is out of range for Element } 
writeln(r =3) { Error: field width must be positive } 
writeln(r 4 : 0); { Error: 2nd field width must be positive } 
{ 
{ 


Smallint := 10; 
a(SmallInt + 11] := 1; { This error is not caught at compile time } 
end; 


Constant or type can't be defined in terms of itself. 
See 1.7 and 3 of Chapter 17. Example: 


const 

aConst = -aConst; { Error } 
type 

TheType = TheType; { Exror } 


RecordPtrType = “RecordType; { OK: type pointed to is } 
{ declared later } 
RecordType = record 
BadNextRecord: “RecordType; { Wrong: can't point to } 
{ defining type } 
NextRecord: RecordPtrType; { Rignt: must use previously } 
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{ declared type } 
NestedRecord : RecordType; { Error: recursively nested } 
{ record } 
end; 


Constant value is not numeric and must not have a sign. 
See 1.7 and 5.1.2 of Chapter 17. Example: 


const 
Dwarves = 7; 
MinusDwarves = —Dwarves; { OK } 
MinusRed = -red; { Error: red is non-numeric } 
MinusChar = -aCharConstant; { Error: non-numeric } 


Constant, expression, or packed type component was passed to a formal VAR 
parameter. 


When a parameter is passed to a formal var parameter, the called subroutine can modify the 
actual parameter passed. Therefore, constants and expressions cannot be passed as var 
parameters, because they cannot be changed. 


Components of packed structures cannot be passed as formal var parameters, because the 
actual data representation of a component in a packed structure may be different from the 
actual data representation in an unpacked structure. (For this Pascal implementation, only the 
representation of packed and unpacked chars are different.) You can pass the entire packed 
structure as a var parameter. 


Note: The predefined procedures read, readin, and readstring are 
special because they can be passed components of packed records. See 
7.3.2 of Chapter 17. 


Example: 


type 
PackedArrayIntType = packed array[1..4] of integer; 
var 
PackedRec : packed record 
il, i2 : integer; 
end; 
Rec : record 
il, i2 : integer; 
end; 
PackedAI : PackedArrayIntType; 
AI : array[1..4] of integer; 


procedure NextInt (var i : integer); 
begin 

ay SSCs by 
end; 
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procedure ChangePAI (var thePAI : PackedArrayIntType ); 


begin 
end; 

begin 
NextInt (5); Error } 
Next Int (anInt+5) ; Error } 
NextInt (PackedRec.i2) ; Wrong } 


NextInt (Rec.i2); Right: works with an unpacked } 
record component } 

Wrong } 

Right: works with an unpacked } 
array component } 

OK: entire packed array can } 
be passed as a VAR parameter } 
OK: readln works on packed } 
structures components } 


NextInt (PackedAI[2]); 
NextInt (AI[2]); 


ChangePAI (PackedAI) ; 


readln (PackedAI [2]); 


end; 


Control variable of FOR statement is not of ordinal type. 
An ordinal type is one of integer, longint, char, or enumerated. See 3.1.1.1 and 6.2.3.3 of 
Chapter 17. Example: 


for aReal := 1 to 10 do { Error: Reals are not ordinal } 
writeln('This will not work'); 
for anInt := 1 to 10 do { OK } 
writeln('anInt =', anInt); 
for aLong := $10000 to $10020 do { OK } 
writeln('aLong =', aLong) ; 
for aChar := 'a' to 'z' do { OK } 
writeln('The letters are ', aChar); 
for aColor := violet downto red do { OK } 
writeln('The colors are ', aColor); 


CYCLE or LEAVE is not in a loop 
You can use the Cycle and Leave procedures only ina for, while, or repeat loop. 


program test; 


var 
x: integer; 
begin 
for x := 1 to 10 do 
begin 
writeln('This line will be written once.'); 
leave; 
writeln('This line will not be written.'); 
end; 
for x := 1 to 5 do 
begin 
writeln(x : 1, ': This line will be written five times.'); 
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cycle; 
writeln('This line will not be written.'); 
end; 
cycle; { ERROR } 
leave; { ERROR } 


end. 


Divide by zero. 
An integer-type division resulted in a division by zero, If the division was floating point, the 


“SANE Floating Point Error” would occur instead. Example: 


anInt := anInt div 0; 


Division by zero attempted. 
Your program attempted to divide by zero. 


program test; 


var 
x: integer; 
begin 
x := 5 div 0; { ERROR } 
x := 5 mod 0; { ERROR } 
end 


Duplicate case constant in this variant-part or CASE statement. 


Case constants must be unique within a case statement or record-variant. See 3.2.2 and 
6.2.2.2 of Chapter 17. Example: 


type 
BadVariantRecordType = record 
case tag : integer of 
Oo: ( { OK } 
i: integer; 
iG 
Os: f { Error: second 0 case } 
ri: real; 


dF 


end; 
begin 
case anInt of 
a 
writeln ('two'); { OK } 
22 
writeln('twice'); { Error: second 2 case } 
end 
end; 
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END needed to complete the above record declaration. 
See 3.2.2 of Chapter 17. Example: 


procedure P1; 


type 
GoodRecordType = record 
aField : integer; 
end; { Right ) 
BadRecordType = record 
aField : integer; 
{ Wrong: Missing end for record declaration } 


begin 
end; 


END. is required at the end of the file. 
You must have end. at the end of your file. Make sure all you begins are matched by ends. 


Execution halted. 

Statements in the Instant window and expression evaluation in the Observe window usually 
finish instanuy (see Chapter 9). If they don't, you can halt them by clicking on the Bug Spray 
Can. After halting the Instant window, THINK Pascal displays the message “Execution 
halted.” After halting the Observe window, the message “Execution halted” appears in the 
value cell of the halted expression. 


Expression can't be cast to the specified type. 

When two variables are type-incompatible, they cannot be used interchangeably, even if they 
are the same size (as determined by sizeof). Casting bypasses this strong type-checking 
feature of Pascal. A cast changes a variable's type, but not its contents. For most casts, the two 
types must be of the same size. For example, on the MC68000 pointers and longints are type- 
incompatible, although both are 32 bits long. Type casting allows them to be used 
interchangeably. 


All casting is machine dependent and potentially dangerous. Use with caution. See 5.4 of 
Chapter 17. Example: 


procedure ExamplesOfCasts; 


type 
LargeAType = array[1..1000] of integer; 
BigRType = record 
aComponent : LargeAType; 


end; 

SmallRType = record 
aComponent : integer; 
end; 


Packed4Type = packed array[1..4] of char; 
TwoIntType = array[1..2] of integer; 
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var 
Big : BigRType; 
Small : SmallRType; 


Packed4 : Packed4Type; 


TwoInt : TwoIntType; 
Large : LargeAType; 
begin 


aLong := longint (aReal) ; 


aLong := round (aReal) ; 
aReal := real (aLong) ; 
aReal := aLong; 

aLong 


Big 
Large 


anInt 
Large 


= longint (Packed4) ; 
BigRType (Small) ; 
LargeAType (Big) ; 
Small := SmallRType (Big) ; 

:= integer (Small); 
LargeAType (Packed4) ; 


{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 


TwoInt := TwoIntType (Packed4) ; 


end; 


Expression must be constant 


Legal, BUT just copies bits, } 

doesn't convert to longint } 

This converts Real type to } 

equivalent Longint type. } 

Legal, BUT just copies bits, } 

doesn't convert to real } 

This converts Longint type to } 

equivalent Real type } 

OK: aLong and Packed4 are same size } 

Error: different sized records } 

OK: Big and Large are the same size } 

Error: different sized records } 

OK : anInt and Small are same size } 
{ Error: different size array } 

{ OK: TwoInt and Packed4 } 

{ are the same size array } 


THINK Pascal lets you declare constant expressions in your const declarations, but the 
expressions must be scalar — integer, boolean, or char 


program test; 


var 
x: integer; 
const 
a= 1; 
b= 2; 
c= a + b; 
d = ((a + b) * 2) div 
e@= 3.2 + 2.8; { 
£= (a +b) / ¢; { 
g=eatb+ x; { 
begin 
end. 


Expression too complex. 


{ 
c; { 
ERROR: 
ERROR: 
ERROR: 


Correct } 

Correct } 

constant expressions must be scalar } 
(constant expressions must be scalar } 
'x' is a variable } 


Try simplifying your expression. Use temporary variables for intermediate results if 


necessary. 
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Field name expected. “symbol!” isn't a field of this record. 
See 4.3.2 of Chapter 17. Example: 


var 
NotAField : integer; 
rec_1 : record 
field_1 : integer; 
end; 
REC_2 : record 
FIELD 2 : integer; 
end; 
begin 
rec_1.NotAField := 0; Wrong: NotAField is not a field } 
of any record } 
Right } 
Wrong: field 1 is a field of rec_1, } 
not of REC 2 } 
Right } 


rec_1.field 1 
REC_2.field 1 


1 
0; 


REC_2.FIELD_2 := 1; 
end; 


File already open. 
A file-variable can only be used once per open file. See 9.2.3 of Chapter 17. Example: 


var 

NEWFILE, oldFile : Text; 
begin 

rewrite (NEWFILE, 'a new file'); 

open(NEWFILE, ‘an old file'); { Wrong: file-variable NEWFILE } 

{ is already in use } 

open(oldfile, ‘an old file'); { Right: use another file variable } 

end; 


File is not open. 


This run time error occurs when any input or output operation is done using a file-variable 
that has not been previously opened or that is already closed. See 9.2.4 of Chapter 17. 
Example 


var 
£ #: Dexts 
TextFile : Text; 
begin 
close (f); { Error: file was not previously opened } 
rewrite(f, 'new file'); 
writeln(f, 'hello'); 
close(f); { OK } 
close (f); { Error: file closed in previous statement } 


write (TextFile, anInt); { Error: TextFile was nenver opened } 
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read(TextFile, anInt); { Error } 


page (TextFile) ; { Error: page does an implicit write to a file } 
get (TextFile) ; { Error: get does an implicit read of a file } 
end; 


File is not opened for random access. 
Only files opened with the procedure open are read-write. The procedure seek can be used 
only with read-writefiles. See 9.2.8 of Chapter 17, Example: 


rewrite(FileOfInt, ‘new file'); 

seek (FileOfInt, 0); { Error } 
close(FileOfInt ); 

reset (FileOfInt, 'old file'); 

seek (FileOfInt, 0); { Error } 
close(FileOfInt ); 

open (FileOfInt, 'old file'); 

seek (FileOfInt, 0); { OK } 
close (FileOfInt ); 


File is not opened for reading. 
Files opened with rewrite are write only. See 9.3.1 and 9.4.1 of Chapter 17. Example: 


REWRITE (TextFile, 'WriteOnly File'); 


get (TextFile); { Error } 
read(TextFile, anInt); { Error } 
readln(TextFile, anInt); { Error } 


File is not opened for writing. 


Files opened with reset are read-only, so you cannot write to them. See 9.2, 9.3.1, and 9.4.1 
of Chapter 17. 


RESET (FileOfText, ‘old file'); 
put (FileOfText) ; { Error } 
writeln(FileOfText, 'Error: cannot writeln to ReadOnly file'); 


FOR loop control variable modified 


Within a for loop, your program is not allowed to alter the value of the control variable. Use 
Cycle or Leave to alter control in the loop. 


for anint := 1 to d do 
anint := 5; { ERROR: can’t modfiy control variable } 
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FOR statement control variable must be a local variable. 


The Pascal language requires £or-loop contol variables to be declared at the same level that 
they are being used. See 6.2.3.3 of Chapter 17. Example: 


program ForLoopControlVariables; 


var 
Outside : integer; { can only be used in main program } 
procedure SubProcedure (aParam : integer); 
var 
local : integer; 
begin 
for integer := 1 to 10 do { Error: integer isn't a variable } 
for aParam := 1 to 10 do { Error: aParam isn't a local variable } 
for Outside := 1 to 10 do { Error: Outside isn't local variable } 
for local := 1 to 10 do { OK } 
end; 
begin 
for Outside := 1 to 10 do { OK: Outside is local to main program } 
end. 


Formal parameter type or result type should be a named type or STRING. 
When a type is used in a parameter list or in a function result declaration, it must be a named 


type. It cannot be an anonymous type, although this is allowed in a variable declaration. See 
7.2 and 7.3 of Chapter 17. Example: 


type 
ArrayType = array(1..2] of char; 
var 
Array_1 : array[0..2] of set of char; { OK: Array_1 is of } 
{ an anonymous type } 
Array_2 : ArrayType; { OK: Array 2 is of a named type } 
function BadArray : array[1..2] of char; { Wrong } 
begin 
end; 
function GoodArray : ArrayType; { Right } 
begin 
end; 
type 
s25Type = string[25]; 
function BadString25 : string[25]; { Wrong } 
begin 
end; 
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function GoodString25 : s25Type; { Right } 
begin 

end; 

function GoodString : string; { Also Works } 
begin 

end; 


type 
IntegerPtrType = “integer; 
function BadResult : *integer; { Wrong } 
begin 
end; 
function GoodResult : IntegerPtrType; { Right 
begin 
end; 


{ Formal parameters must also have named types } 

procedure BadParam (p : “integer); { Wrong: “integer isn’t named type } 
begin 

end; 

procedure GoodParam (p : IntegerPtrType); { Right } 

begin 

end; 


Formal value parameter can't be a file type or a type which contains a file type. 


For every open file, there must be only one copy of the file-variable. The operating system 
needs file-variables for file input/output. If a copy of the file-variable could be made and 
both were used for file I/O, then the file would be inconsistent. Therefore, passing a file- 
variable parameter by value (which makes a new copy) is forbidden. Passing a file-variable 
as a var parameter is permitted. See 7.3.1 of Chapter 17. 


type 
IntFile = file of integer; 
RecWithFileType = record 
FileName : string; 
FileParameter : file of real; 
end; 
ArrayOfFileType = array[1..3] of file of integer; 


procedure Badl (F : IntFile); { Wrong: passing a filetype by value } 

begin 

end; 

procedure Goodl (var F : IntFile); { Right: pass it as VAR parameter } 

begin 

end; 

procedure Bad2 (R : RecWithFileType); { Wrong: passing a filetype } 
{ by value } 

begin 

end; 

procedure Good2 (var R : RecWithFileType); { Right } 


Messages E 


begin 

end; 

procedure Bad3 (A : ArrayOfFileType); { Wrong: passing a filetype } 
{ by value } 

begin 

end; 

procedure Good3 (var A : ArrayOfFileType); { Right } 

begin 

end; 


FORWARD or INTERFACE procedures or functions may not later be declared 
INLINE. 


See 7.1.3 of Chapter 17. Example: 


unit BadInLine; 


interface 
function InterfaceFunc (x : char) : char; { INTERFACE declaration } 
implementation 
function InterfaceFunc; 
inline { Error: inline not permitted with INTERFACE } 
$4E71; { MC68000 NOP Instruction } 
procedure ForwardProc (x : char); { FORWARD declaration } 
forward; 
procedure ForwardProc; 
inline { Error: inline not permitted with FORWARD } 
$4E71; 
end. 


Function name required as an actual parameter to a formal functional parameter. 


Functional parameters are a way of passing functions as parameters. See 7.3.4 of Chapter 17. 
Example: 


function Func (i : integer) : integer; 
begin 
end; 
procedure Proc (i : integer); 
begin 
end; 
procedure CallF (function aFunc (i : integer) : integer); 
begin 
anInt := aFunc(4); 
end; 
procedure RecallF (function aFuncParam (i : integer) : integer); 
begin 
CallF (Func) ; OK: CallF is passed a function } 


{ 
CallF (aFuncParam) ; { OK: CallF is passed a functional parameter 
CallF (4); { Error: an integer is passed } 
CallF (Proc); { Error: a procedure is passed } 
end; 
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GOTO out of Observe/instant not allowed. 


Because of the special nature of Observe and Instant windows, non-local gotos, which 
directly or indirectly exit a subroutine's current scope, are not allowed. For example, if you 
halted on the statement writeln; (see below) and then attempt to Observe the value of 
Escape, you will see this message in the value cell because of the goto 9999 statement. 
The goto 1 statement is a local goto and does not exit the Escape's current scope. 
Furthermore, normal execution of Escape within your program will work without error. 


program Escape; 


label 
9999; 
function Escape:integer; 
label 1; 
begin 
goto 1; { OK when Escape is called in Observe or Instant } 
anInt := 0; 
1: goto 9999; { Error when Escape is called in Observe or Instant } 
Escape := 42; { This statement is never executed } 
end; 
begin 
writeln('stop here'); 
anInt := Escape; { OK to call Escape within the program } 
9999: 
end. 


Illegal Instruction Exception 


This runtime error indicates your program has run amok. For some reason, your program has 
jumped off into a random place in memory, or your code has been overwritten (e.g. by an 
uninitialized pointer), or the Memory Manager may be corrupted. Unless you can reproduce 
this behavior, it may be very hard to track down the problem and to fix it. You may have to 
use a low level debugger. (There are several bit patterns that are not legal MC68000 
instructions. Your program was trying to execute one of these.) 


Index out of range. 


This runtime error occurs when a Pack or Unpack procedure is called with a bad index or 
inappropriate structures. See 10.2.1 and 10.2.2 of Chapter 17. Example: 


var 
pacl0O : packed array[1..10] of char; 
pac7 : packed array[1..7] of char; 
acl0 : array[1..10] of char; 
ac7 : array [1..7] of char; 
begin 
anInt := 1; 
pack(ac7, anInt, paclO); { Error: ac7 is too small to } 
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fit into paclO } 
OK for only anInt = 1 } 
OK for values of anInt = 1..4 } 
Error: pacl0O is too large to } 
fit into ac7 } 

unpack (pacl0, acl0O, anInt); { OK for only anInt = 1 } 

unpack (pac7, acl0, anInt); { OK for values of anInt = 1..4 } 
end; 


pack(acl0, anInt, pacl0); 
pack(acl0, anInt, pac7); 
unpack (pacl0, ac7, anInt); 


InitGraf's parameter must be @thePort. 


This runtime error occurs when the predefined Macintosh Toolbox call InitGraf is used 
with a parameter other than @thePort. This error is only detected while running with the 
THINK Pascal environment. See Inside Macintosh for more details. Example: 


InitGraf (@anInt) ; { Wrong } 
InitGraf(@thePort); { Right } 


Insufficient stack space to invoke procedure or function. 


This runtime error occurs when a subroutine, compiled with the Debug compile option, 
determines that there is not enough stack space remaining for it. It may be that too many 
nested subroutine calls have used too much stack space for local variables. However, your 
heap is probably unharmed. The solution may involve fixing an out of control recursive 
subroutine or increasing your application's stack size with the Run Options... command. 
Use LightsBug to examine the Subroutine Call Chain. See Chapters 13 and 15. Example: 


procedure EndlessRecursion (i:longint) ; 
begin 

EndlessRecursion (itl) ; { Eventually, stack space will run out here } 
end; 


Integer overflow. 


The Overflow compile option inserts code that checks for intermediate arithmetic operation 
overflows. (See Chapter 15). This runtime error occurs when this check fails. Example: 


anInt := 21000; 
anInt := anInt + 20000; { Error: the sum 41000 overflows anInt, } 
{ resulting in the erronous value -—24536 } 


INTERFACE expected here. 
See 8.3 of Chapter 17. Example: 


unit MissingKeywordINTERFACE; 

{ Error: missing interface keyword here } 
implementation 
end. 
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Invalid .o file 


The MPW object file THINK Pascal is trying to read is not in a format THINK Pascal 
understands. It may have been produced by the wrong version of MPW. 


Invalid formal parameter list. 
The parameter list in a function or procedure declaration is bad. See 7.3 of Chapter 17. 


Example: 
procedure BadProc_1 (1, 2 : integer; { Wrong : bad parameter names } 
ExtraSemiColon : integer; { Wrong : extra (;) after last parameter } 
dF 
begin 
end; 
procedure GoodProc_1 (one, two : integer; { Right } 
LastParameter : integer { Right } 
ye 
begin 
end; 
procedure BadProc 2 (x, y : 
INTEGER var z: char ); { Wrong: missing ; after INTEGER } 
begin 
end; 
procedure GoodProc_2 (x, y : INTEGER; { Right } 
var z : char); 
begin 
end; 
{ Wrong: aProc is declared as a procedure but has a result type CHAR } 
procedure BadCallF ( procedure aProc (i : integer) : CHAR); 
begin 
aProc(5); 
end; 


{ Right: aProc is correctly declared as a procedural parameter } 
procedure GoodCallP ( procedure aProc (i : integer)); 
begin 
aProc(5); 
end; 
{ Also Right: aFunc is correctly declared as a functional parameter } 
procedure GoodCallF (function aFunc (i : integer) : char); 
begin 
aChar := aFunc(5); 
end; 


Invalid INLINE constant. 
Only 16-bit integer values are allowed for inline constants. See 7.1.3 of Chapter 17. Example: 


{ Inline routine to Call a procedure through a pointer } 

procedure Wrong_JSR_To(PtrToProcedure: Ptr); 

inline { Wrong: constants must be word sized } 
$20S5F4E90; 
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procedure Right_JSR_To(PtrToProcedure: Ptr); 


inline { Right: each constant is word sized } 
$205F, { MOVEA.L (SP)+,A0 } 
$4E90; { JSR (AO) } 

procedure Proc; 

begin 

end; 

procedure Call; 

begin 
Right_JSR_To (@Proc) ; 

end; 


Invalid list of field names. 
Field names must be legal Pascal identifiers. See 1.2 and 3.2.2 of Chapter 17. Example: 


type 
InvalidFieldName = record 
Legal, 5, AnotherName : integer; { Error: 5 is bad field name } 
end; 


Invalid list of variable names. 
Variable names must be legal Pascal identifiers. See 4.1 of Chapter 17. Example: 


a, 1, 2, ¢ : integer; { Error: 1 and 2 aren't legal variable names } 


Invalid OBJECT typecast. 
You can cast an object only to an ancestor object. 


program test; 
uses 
ObjIntf; 
type 
AnObj = object (TObject) 
end; 
AnotherObj = object (TObject) 
end; 
ExpandedObj = object (TObject) 
Xx, y, z: integer; 
function func: boolean; 
end; 
function ExpandedObj.func: boolean; 
begin 
func := true 
end; 


var 
a, w: AnObj; 
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b, x: AnotherObj; 
c, y: ExpandedObj; 
d, z: TObject; 


begin 
new (w) ; 
new (x) ; 
new (y); 
new (z); 
d := TObject (x); { Correct } 
d := TObject (y); { Correct } 
d := TObject (z); { Correct, but z is already a TObject } 
c¢ := ExpandedObj (x); { ERROR if Range checking is on } 
c := ExpandedObj (z); { ERROR if Range checking is on } 
b := AnotherObj(w); { ERROR if Range checking is on } 
b := AnotherObj(y); { ERROR if Range checking is on } 
b := AnotherObj(z); { ERROR if Range checking is on } 
end. 


Invalid PROGRAM parameter list. 
See 8.2 of Chapter 17. 


Invalid redeclaration of method 
You've tried to declare a field of an object as a method. 


program test; 
uses 
ObjIntf£; 
type 
TestObj = object (TObject) 
x: integer; 
end; 
procedure Test0Obj.x; { ERROR: 'x' is a field, not a method } 
begin 
end; 
begin 
end. 


Invalid result type in function declaration. 
See 7.2 of Chapter 17. Example: 


function BadF1; { Wrong: missing result type } 

begin 

end; 

function GoodFl : char; { Right } 

begin 

end; 

function BadF2 (c : char)char; { Wrong: missing colon in result type } 
begin 

end; 
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function GoodF2 (c : char) : char; { Right } 

begin 

end; 

function GoodF3 : char; { OK: forward definition of GoodF3 } 
forward; 


function GoodF3; { OK: definition of forward function may leave off } 
begin { its result type } 
end; 


{ Wrong: missing result type for formal functional parameter “aFunc” } 
procedure BadCall (function aFunc (c : char)); 

begin 

end; 

{ Right } 

procedure GoodCall (function aFunc (c : char) : CHAR); 

begin 

end; 


Invalid variable, field, or formal parameter list. A colon (:) might be missing. 


When a variable name is declared, a corresponding type must be provided. See sections 3 
and 4 of Chapter 17. Example: 


var 
VariableWithoutAType; { Wrong: missing type } 
Variable : integer; { Right } 
aRecord : record 
FieldWithoutAType; { Wrong: missing type } 
GoodField : integer; { Right } 
end; 
procedure P (aParamWithoutAType; { Wrong: missing type } 
aGoodParam : integer); { Right } 
begin 
end; 


Invalid variant declaration. 
See 3.2.2 of Chapter 17. Example: 


type 
BadVariantRecordType = record 
case i: integer of 
HR aa 
a, b : char; { OK } 
; 
vA SEL f 
{ Right: OK to have empty variant } 
Ve 
Biz 
r { Wrong: Missing () for empty variant} 
end; 
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Label has already been declared. 
See 2.2.4 of Chapter 17. Example: 


program BE 70; 
label 
6; 
procedure SubProc; 
label 
6;{ OK: This label is in a different scope } 
procedure SubSubProc; 
label 
6; { OK: This label is in a different scope } 
label 
6; { Error: duplicate label declaration in SubSubProc } 
begin 
6: 
end; { SubSubProc } 
begin 
6: 
end; { SubProc } 
begin 
6: 


end. 


Label has already been used to label a statement. 
See 2.2.4 of Chapter 17. Example: 


procedure Proc; 
label 


writeln('OK'); 
13's 

writeln('Error: another statement with a label 13 at this level'); 
end; 


Label has not been used to label any statement. 


Labels must label a statement at the level where the label is declared. See 2.1 of Chapter 17. 
Example: 


program UsingLabels; 
procedure Zero; 
label 
0; { Error: label is not used in procedure which declared it } 
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begin 
writeln; 
end; 
begin 
end. 


Label hasn't been declared at this level. 
Statements can only be labeled with labels declared at the same level. See 2.1 and 6 of 
Chapter 17. Example: 


program UsingLabels; 


label 
1; 
procedure ZeroAndOne; 
label 
Oy a? 
begin 
Oo: 
il! 
end; { ZeroAndOne } 
begin 
13 : { Error: 13 was never declared } 
writeln('Statement Labeled with 13'); 
Q : { Wrong: 0 was not at this level } 
writeln('Statement Labeled with 0'); 
1: { Right: irrelevant if 1 was declared in ZeroAndOne } 
writeln('Statement Labeled with 1'); 
end. 


Label was not declared at the same level as this statement. 


Statements can only be labeled with labels declared at the same level. See 2.1 of Chapter 17. 
Example: 


program UsingLabels; 


label 
Lay { declares labels for use in main program } 
procedure SubProc; 
begin 

1 { Wrong: label 1 hasn't been declared at this level } 
goto 2; { OK to GOTO a label at an outer scope } 
end; { SubProc } 

begin 

ap! os { Right: label 1 must be used at this level } 
writeln('statement labeled with 1'); 

2 4 { Right: label 2 must be used at this level } 
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writeln('statement labeled with 2'); 
end. 


Library must contain at least one file. 


When you use the Build Library... command, the project must contain at least on file. See 
Chapter 10. 


Library must contain only one code segment. 


The project you are trying to build into a library contains more than one segment. Before you 
can build it, you must either (1) combine the segments into a single segment or (2) break up 
your project into multiple single-segment projects and build a library for each project. To see 
how your project is segmented, click on the view control in the upper right corner of the 
project window. See Chapters 7 and 10. 


Library must not contain a main program. 
Libraries are not allowed to have a main program. 


Link Failed: multiply-defined: “symbol” 


¢ Have you included two different versions of the same library into your project? 
e Does a library contain an extraneous Runtime.1ib or Interface.1lib? 


Link Failes: undefined: “symbol” 


e Have you added all necessary libraries to your project? 
¢ Have you declared a subroutine external and never defined it in one of your libraries? 


Lower boundary of subrange is greater than upper boundary. 


For types, the lower bound must be less than the upper bound. For set constructors, the 
lower bound can be greater than the upper bound, in which case the set is empty. See 3.1.1.3 
and 5.3 of Chapter 17. Example: 


procedure Proc; 


var 

BadColor : blue..red; { Error } 

BadSubrange : 3..1; { Error } 

aSet : set of ColorType; 
begin 

aSet := [blue..red]; { OK: aSet is empty } 
end; 


Macintosh System Error: —nnn 
One of the more obscure Macintosh errors has occurred. See Inside Macintosh. 
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Macsbug/TMON not installed 


Your program tried to execute a Debugger or DebugStr procedure when a low level 
debugger wasn’t installed. 


program test; 


begin 
Debugger; { ERROR if no low-level debugger is installed } 
DebugStr('Break in TEST'); { ERROR: same reason } 

end. 


MC68881: divide by zero 
MC68881: inexact 
MC68881: not a number 
MC68881: operand error 
MC68881: overflow 
MC68881: underflow 


You'll get these errors only when you have the MC68881 option on (see Chapter 15) and 
you've enabled halts for certains conditions. (See the Set Halt routine in the Apple Numerics 
Manual.) 


Method not found. 
The method you tried to invoke doesn’t exist for the object you’re using. 


program test; 
uses 
ObjIntf; 
type 
AnObj = object (TObject) 
procedure proc; 
end; 
procedure AnObj. proc; 
begin 
end; 


var 
T: TObject; 
A: AnObj; 
begin 
new (T); 
a := AnObj(T); 
a.proc; { ERROR } 
end. 
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Method not inherited by this object 


You used the inherited keyword in front of a method name, but the object you’re 
referencing doesn’t inherit that method. 


program test; 
uses 
ObjiIntf; 
type 
AnObj = object (TObject) 
end; 
AnotherObj = object (AnObj) 
function func: boolean; 
end; 
function AnotherObj.func: boolean; 
begin 
func := true; 
end; 


var 
x: AnotherObj; 
b: boolean; 


begin 
new (x); 
b := x.func; { Correct } 
with x do 
b := func; { Correct } 
with x do 
b := inherited func; { ERROR } 
end. 


Missing or invalid unit name in this USES. 
See 8.1 of Chapter 17. Example: 


program WithBadUSES; 
uses 


4; { Error: invalid unit name } 
begin 
end. 


NIL dereference. 


The Range compile option inserts code into your program which checks for nil pointer 
dereferences (see Chapter 15). This runtime error occurs when this check has failed. 
Sometimes the actual cause of this error is long gone from the scene, but often the culprit is 
close at hand. You may be able to find the problem using Observe and LightsBug. 
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Note: If the pointer is not initialized before assignment, then you probably 
will not get this error. Instead, some piece of memory may be corrupted. 
Later, an Odd Address or an Illegal Instruction may occur. 


Example: 


{ Assumes the Range compile option is On } 


var 
IntPtr : “integer; 

begin 
IntPtr := nil; { It's important to initialize Pointer Variables! } 
IntPtr® 13; { Wrong: IntPtr is a NIL pointer } 
IntPtr := @anInt; { This makes sure that IntPtr points to something } 
new(IntPtr); { Also makse sure that IntPtr points to something } 
IntPtr®* := 13; { Right: IntPtr now points somewhere } 

end; 

No context 


This message appears in the value cells of the Observe window when your program is not 
running, paused, or halted. Because there is no program context, expressions (even 
constants) cannot be evaluated. 


No windows are available for opening your file. 


You can open up to eight edit windows to edit files. This number does not include the Instant 
and Observe windows. If you get this message, you'll need to close some files. Remember 
that THINK Pascal doesn’t close files when you click on a window’s close box. You need to 
use the Close command in the File menu to close a file. You can also hold down the 
Command key as you click in the window’s close box. 


Not previously declared as a method 
You’re trying to define a method that you didn’t include in the object's declaration. 


unit unitl; 
interface 
uses 
ObjIntf; 
type 
TestObj = object (TObject) { Declare object type "TestObj" } 
function func: boolean; { Declare method "TestObj.func" } 
end; 
implementation 
function TestObj.func: boolean; { Implementation of method } 
{ "TestObj.func" } 
begin 
fune := true 
end; 
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procedure TestObj.proc; { ERROR: this method wasn't declared } 
{ in the declaration of TestObj } 
begin 
end; 
end. 


Objects and Methods may not be declared in nested scopes 


Objects and methods must be defined in the outermost scope. Proecdures and functions 
cannot define objects or methods. 


program test; 
uses 
Objintf; 
procedure proc; 
type 
TestObj = object (TObject) { ERROR: trying to declare object } 
end; { within scope of "proc" } 
begin 
end; 
begin 
end. 


unit unitl; 
interface 
uses 
ObjIntf; 
procedure proc; 
type 
TestObj = object (TObject) { Object "TestObj" } 
function func: boolean; { Method "TestObj.func" } 
end; 
implementation 
procedure proc; 
function TestObj.func: boolean; { ERROR: can’t declare method } 
begin { within scope of "proc" } 
end; 
begin 
end; 
end. 


Operand type incompatibility. 


Some operations aren't allowed, though it seems they ought to be. For example, record 
assignments are legal because it is easy to do a blind byte copy. However, record 
comparisions are forbidden, because a blind byte comparision will not work ,and anything 
else is too hard. In particular, two equivalent structures can have different bit patterns 
because of byte padding or different garbage in inactive variants. The solution is to write your 
own comparision functions for records and arrays. (Note: it is permitted to compare packed 
arrays of characters.) 
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The following examples show common errors and methods to break the rules. Use the 
methods at your own risk. See 3.5 and 5 of Chapter 17. 


var 

AC1l, AC2 : array[1..10] of char; 

PAC1, PAC2 : packed array[1..10] of char; 

PAI1, PAI2 : packed array[1..10] of integer; 

Recl, Rec2 : packed record 
IntFieldl : integer; 
CharField : char; { byte of pad between IntFieldl and IntField2 } 
IntField2 : integer; 

end; 

PERL, PEE! 2 .pEXS 

stringl, string2, string3 : string; 


begin 
stringl := string2 + string3; { Wrong } 
stringl := concat(string2, string3); { Right: see 10.5.3 of } 
{ Chapter 17 } 
aBool := (aReal <> anInt); OK to compare real with integer } 
aBool := (aString <> ACl); Wrong: can't compare strings with } 


{ 
{ 
{ UNpacked char array } 

aBool : (aString <> PAC1); { Right: OK to compare strings with } 
{ 
{ 


packed char array } 


anInt := 3.5 mod 4.5; Wrong: MOD can't take real arguments } 
anInt := 3 mod 4; { Right } 

aColor red + blue; { Wrong: can't use + on enumerated types } 
aColor ColorType (ord (red) +ord (blue) ) ; { Right: BUT is this } 

{ really meaningful? } 
aBool := (ptrl > ptr2); { Wrong: ptrs have no ordering } 
aBool := (longint (ptr1l)>longint (ptr2)); { Right: BUT is this } 

{ really meaningful? } 
aBool := (ptrl <> ptr2); { OK: can only use = and <> on ptrs } 
AC1l := AC2; { OK: it's legal to assign unpacked arrays } 
aBool := (ACl <> AC2); { Wrong: can't use =, <>, etc. } 
{ on unpacked char arrays } 
aBool := (PAC1 <> PAC2); { Right: OK to compare packed CHAR array } 
aBool := (PAC1 > AC1l); { Error: can't compare packed and } 
{ unpacked CHAR array } 
aBool := (PAI1 <> PAI2); { Error: can't compare packed arrays } 
{ of NonChars} 
, Recl := Rec2; { OK to assign records } 
aBool := (Recl = Rec2); { Error: can't compare records this way } 
end; 


OVERRIDE expected 


If you want to redefine a method that belongs to an ancestor object, you need to use the 
override directive. 
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program test; 
uses 
ObjIntf; 
type 
AnObj = object (TObject) 
function func: boolean; { OK method "AnObj.func" } 
end; 
AnotherObj = object (AnObj) 
function func: boolean; { Error: need “override” if re- } 
end; { defining method } 
function AnObj.func: boolean; 
begin 
func := true 
end; 
function AnotherObj.func: boolean; 
begin 


Parameter list doesn't match previous declaration 


THINK Pascal lets you repeat the parameter list for procedures and functions defined in the 
interface section or for routines declared forward. The parameter lists must match exactly. 
Note that parameters of type string do not match. You must create a type for them. 


unit unitl; 
interface 
procedure proc (x, y, z: integer); 
implementation 
procedure proc (x, y, z: longint); 
{ ERROR: type should be "integer" } 
begin 
end; 
end. 


Period (.) required following the last END of the file. 
See 8.1 of Chapter 17. Example: 


program MissingPeriod; 
begin 
end { Error: Missing period } 
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Predefined and inline procedure names can't be used as procedural parameters. 


Predefined, Toolbox, or inline calls (which aren't genuine subroutines) cannot be passed as 
procedural or functional parameters. However, you can write a wrapper routine (which 
wraps itself around the desired subroutine) that you can pass as a procedural or functional 
parameter. See 7.3.3 of Chapter 17. Example: 


program ProceduralAndFunctionalParameters; 
procedure CallF (function F (e : Extended) : integer); 
begin 
end; 
procedure CallP ( procedure P); 
begin 
end; 
procedure NOP; 
inline 
$4e71; { M68000 NOP instruction } 
procedure NOPWrap; 
begin 
NOP; 
end; 
function TruncWrap (e : Extended) : integer; 
begin 
TruncWrap := Trunc(e); { Predefined function } 
end; 
procedure OpenRgnWrap; 
begin 
OpenRgn; 
end; 
begin 
CallF (Trunc) ; { Wrong: Trunc is predefined function } 
CallF (TruncWrap) ; { Right: Trunc is called from TruncWrap } 
CallP (NOP) ; { Wrong: NOP is an inline procedure } 
CallP (NOPWrap) ; { Right: NOP is called from NOPWrap } 
CallP (OpenRgn) ; { Wrong: OpenRgn is a Toolbox procedure } 
CallP (OpenRgnWrap); { Right: OpenRgn is called from OpenRgnWrap } 
end. 


Printer port in use by AppleTalk. 
You will have to use the modem port instead. If you really want to use AppleTalk, see Inside 
Macintosh and Chapter 8. 


Procedure name required as an actual parameter to a formal procedural parameter. 
See 7.3.3 of Chapter 17. Example: 


function Func (i : integer) : integer; 
begin 

end; 

procedure Proc (i : integer); 
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begin 
end; 
procedure CallP ( procedure aProc (i : integer)); 
begin 
aProc (4); 
end; 
procedure RecallP ( procedure aProcParam (i : integer)); 
begin 
CallP (Proc); { OK: CallP is passed a procedure } 
CallP(aProcParam); { OK: CallP is passed a procedural parameter name 
} 
CallP (4); { Error: an integer is passed } 
CallP (Func) ; { Error: a function is passed } 
end; 


Procedure or function has a FORWARD declaration but was never defined. 


The subroutine declarations that use the forward directive allow you to defer the 
subroutine's definition. However, the definiton must appear later in the file. See 7.1.1 and 8.3 
of Chapter 17. Example: 


unit aUnit; 

interface 

implementation 
procedure aForward; { Error: never defined later in this unit. } 
forward; 

end. { end of unit } 


PROGRAM or UNIT is missing from the beginning of this file. 
You must have the keyword program or unit at the beginning of your file. 


Project has a code segment larger than 32K. 


The Macintosh Segment Loader requires a code segment to be smaller than 32767 bytes. You 
must split up your file into smaller files and put them into different segments. See Chapter 7. 


Project has more than 32K bytes of globals. 


The total size of all the global variables in your project must be less than 32K. If you need to 
create variables that require a lot of space, use the Memory Manager to allocate the space on 
the heap. Remember that THINK Pascal lets you declare array types that are bigger than 32K. 


unit unitl; 
interface 
type 
BigArrayType = packed array[0..16500] of char; 
BAPtr = “BigArrayType; 
BAHandle = “BAPtr; 
var 
BigArrayl: BigArrayType; { one 16501-byte global variable } 
implementation 
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end. 


program test; 
uses 
unitl; 
var 
BigArray2: BigArrayType; { another 16501-byte global variable } 
{ Error here. } 
BigArray3 : BAHandle; 


begin 
BigArray3 := BAHandle (NewHandle (sizeof (BigArrayType) ) ) ; { OK } 
BigArray3**(16000] := 'x'; 

end. 


Project has no main program. 


In order for your program to run, a file which contains a main program needs to be added to 
your project. The file should contain the program keyword. 


READLN and WRITELN can only be used with text files. 


The predefined procedures read1n and writeln only work with text files. Use read, 
write, put or get for all other types of files. See 9.3 and 9.4 of Chapter 17. Example: 


procedure Proc; 


var 
FileOfChar : file of char; { not the same thing as text } 
PackedFileOfChar : packed file of char; { not the same thing as text } 
FileOfInt : file of integer; { not at all the same as text } 
begin 
open(TextFile, 'Text File'); 
writeLN(TextFile, 4); { OK } 
readLN(TextFile, anInt); { OK } 


open (PackedFileOfChar, ‘packed file of CHAR'); 
writeLN (PackedFileOfChar, 'a') { Wrong 
write (PackedFileOfChar, 'a'); { Right 
{ 
{ 


readLN (PackedFileOfChar, aChar); Wrong 
read(PackedFileOfChar, aChar) ; Right 
open(FileOfChar, 'file of CHAR'); 
writeLN(FileOfChar, ‘'a') { Wrong } 
write (FileOfChar, 'a'); { Right } 
open(FileOfInt, 'file of INTEGERS'); 
writeLN(FileOfInt, 4); { Wrong } 
write (FileOfInt, 4); { Right } 
end; 
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Record contains no fields. 
Records must contain at least one field. Example: 


type 
RecordType = record 
end; { Error: no fields } 


Record name expected. “symbol!” isn't a record. 
Symbol is not properly used in a record reference. See 6.2.4 of Chapter 17. 


type 

RecordType = record 

aField : integer; 

end; 

RecordPtrType = “RecordType; 
var 

aRecord : RecordType; 

aRecordPtr : RecordPtrType; 
function aFunc : RecordPtrType; 
begin 
end; 

begin 


anInt.aField := { Wrong: anInt is not a record } 


aRecord.aField { Right } 
with anInt do { Wrong: anInt is not a record } 
aField := 3; 
with aRecord do { Right } 
aField := 3; 
new (aRecordPtr) ; 
aRecordPtr.aField:=3; { Wrong: need to dereference pointer) 
aRecordPtr*.aField:=3; { Right: the * makes all the difference } 


end; 


Result can't be assigned to the function named “symbol ” outside of its declaration. 
See 7.2 of Chapter 17. Example: 


program AssigningToFunctions; 
type 
IntPtrType = “integer; 
var 
IntPtr : IntPtrType; 
function aFunction : integer; 


begin 
aFunction := 42; { Right } 
end; 
begin 
aFunction := 42; { Error: outside of function declaration } 
end. 
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Result type doesn’t match previous declaration 


You can repeat the result type of a function you previously declared forward, but the result 
types must match exactly. Example: 


function GregHowe : char; 
forward; 

function GregHowe : integer; 
function GregHowe : char; 
function GregHowe; 


ERROR: Result type must be char } 
OK: Result type matches } 

OK: OK to leave out result type } 
if previously declared forward } 


unit unitl; 
interface 
function PaulVetri: integer; 
implementation 
function PaulVetri: longint; { ERROR: type should be "integer" 
begin 
PaulVetri:= 13; 
end; 
end. 


SANE Floating Point Error 

A SANE (Standard Apple Numerics Enivironmenp call has resulted in an error. Note: a 
Floating point division by zero results in this error, while an integer-type division by zero 
results in the Divide by zero error. Example: 


var 
re real; 
i: integer; 
begin 
f) f= (O25 
for i := 1 to 11000 do 
Ge= 15 * 107 
end; 


SEEK and FILEPOS are only allowed for disk files. 
You cannot use the SEEK and FILEPOS routines on devices like the modem port. 


program test; 
var 
textfile: text; 
position: longint; 


begin 
open(textfile, 'old file'); 
seek(textfile, 0); { Correct } 
position := filepos(textfile); { Correct } 


close (textfile); 
open(textfile, 'MODEM:'); 


431 


THINK’s Lightspeed Pascal 


position := filepos(textfile); { ERROR: textfile is the MODEM: } 
seek (textfile, 0); { ERROR: textfile is the MODEM: device } 
end. 


SEEK of a negative component number not allowed. 
See 9.2.8 of Chapter 17. Example: 


open(FileOfInt, ‘old file'); 

seek(FileOfInt, -1); { Error } 

seek (FileOfInt, 0); { OK: seeks to first component in file } 

seek (FileOfInt,maxlongint) ; { OK: seeks to last component in file } 


Segment Loader error (not enough memory). 


When a subroutine in an unloaded segment is called, the segment loader automatically loads 
it into the heap. This error will occur when there is not enough memory to load the segment, 
You can either increase your Heap size with the Run Options Command..., or use 
UnloadSeg to unload unneeded segments. See Inside Macintosh. If you're running with 
MulltiFinder, increase the size of THINK Pascal’s partition. 


Selector expression of CASE statement isn't of ordinal type. 
See 3.1.1 and 6.2.2.2 of Chapter 17. Example: 


begin 

case aReal of { Error: aReal is not ordinal } 
3.14159 

end 

case ColorSet of { Error: ColorSet is not ordinal } 
[red] 

end 

case anInt of { OK: anInt is ordinal } 
Oo: 

end; 

case aChar of { OK: aChar is ordinal } 
te! 

end; 

case aColor of { OK: aColor is ordinal } 
red : 

end; 

case along of { OK: aLong is ordinal } 
$40000 
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Semicolon (;) or END expected after the previous statement. 
See 6.2.1 of Chapter 17. Example: 


begin 
writeln('Error: Missing SemiColon at end of this line -->') 
writeln('OK: SemiColon not needed at end of this line') 
end; 


Semicolon (;) or UNTIL expected after the previous statement. 
See 6.2.3.1 of Chapter 17. Example: 


begin 
repeat 
writeln ('OK'); 
until false; 
repeat 
writeln('Error: missing semicolon on this line -->') 
writeln 
until false; 
repeat 
writeln('Error: Missing UNTIL'); 
end; 


Semicolon (;) required on this line or above. 
See 2.1, 1.7, 3, 4.1, 7.1,7.2 of Chapter 17. 


label 

0 { Error: missing semicolon at end of line } 
const 

BadConstant = 0 { Error: missing semicolon at end of line } 
type 

BadType = char { Error: missing semicolon at end of line } 
var 

BadVar : integer { Error: missing semicolon at end of line } 
procedure BadProc : CHAR; { Error: procs do not return values } 
begin 
end; 
function BadFunc : char { Error: missing semicolon at end of line } 
, begin 
end; 
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Set constant out of range 

Set value out of range. 

When assigning a value to a set, the range of the resulting set expression must be within the 
range of variable's set type. Example: 


var 
DigitSet : set of 0..9; 
WarmSet : set of red..yellow; 


begin 
DigitSet := [-1, 1]; { Error: -1 not in range 0..9 } 
DigitSet [Se LO]: { Error: 10 not in range 0..9 } 
DigitSet (]; { OK } 
DigitSet (0..9); { OK ) 
DigitSet: = [1, 2, 3, 5) T]p -{ OK } 
if 1000 in DigitSet then { OK: even if 1000 isn't in range 0..9 } 
DigitSet := DigitSet - [10..15]; { OK: expression is in range } 
WarmSet := [blue]; { Error: blue not in range red..yellow } 
WarmSet := []; { OK } 
WarmSet := [red..yellow]; { OK } 


end; 


Set elements must be integer, char or enumerated. 


Set element types are limited. However, in THINK Pascal the ranges are not as limited as in 
other Pascal implementations. See 3.2.2 of Chapter 17. Example: 


type 
ArrayType = array[(1..3] of integer; 
RecordType = record 
aField : integer; 


end; 
SetType = set of char; 

var 
SetOfArray : set of ArrayType; { Error } 
SetOfLongint : set of longint; { Error } 
SetOfRecord : set of RecordType; { Error } 
SetOfReal : set of real; { Error } 
SetOfSet : set of SetType; { Error } 
SetOfColor : set of ColorType; { OK } 
SetOfChar : set of char; { OK } 
SetOfSmalliInts : set of 1..10; { OK } 
SetOfintegers : set of integer; { OK } 


Stack has moved into application heap. 

The stack has overflowed into the heap; the heap is probably damaged. This error, which 
may be more familiar as System Error ID 28, is not always detected. (See Inside Macintosh.) 
In hindsight, you should have compiled with the Debug option, which probably would have 
caught this error safely and in time. (See Chapter 13.) 
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String constant must have length 1 to be compatible with Char. 
See 3.5.3 of Chapter 17. 


const 

aStringConstant = 'Hi'; 

NullStringConstant = ''; 

CouldBeEither = '?'; 
Bbw { Error } 
NullStringConstant; { Error } 
bb { Error } 
"GN { OK } 
CouldBeEither; { OK } 


String constant too large or too small for destination 

When assigning a string constant to a string variable, the string constant must fit. When 
assigning a string constant to a packed array of characters, the length of the string constant 
must be the same as the number of characters in the array. Example: 


s5: string[5]; 
PACS : packed array[1..5] of char; 


"twelve chars'; 
‘five!'; 


Error: length of string constant > 5 } 
OK } 


"twelve chars'; Error: length of string constant <> 5 } 
*four'; Error: length of string constant <> 5 } 
'five!'; OK } 


String range error. 

Do not confuse a string's size with its length. This runtime error is caused by accessing a 
character element of a string with an index outside the range 1. . length (aString). If 
you need to lengthen a string, use the insert procedure or include function. See 3.3, 
4.3.1, and 10.5 of Chapter 17. Example: 


var 
a: integer; 
s: string[8]; 


begin 
s := 'abcdefgh'; 
for a := 1 to 9 do 


writeln(s[a]); 
end; 
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aString := 'foo'; 

aString[3] := 'u'; { OK: current length of aString is 3 } 
aString[4]:= 'r'; { Wrong: can't append to string this way } 
insert ('r', aString, 4); { Right: aString = 'four' } 


String size must be a number between 1 and 255. 
See 3.3 of Chapter 17. Example: 


var 
aStringFloating : string[3.4]; { Wrong: string size not an integer } 
aString256 : string[256]; { Wrong: string size > 255 } 
aStringMinusOne : string[-1]; { Wrong: string size < 1 } 


aString5 : string[5]; { OK } 


String too large. 


If a string is being read into by a read, read1n, or readst ring statement, the destination 
string must be big enough to accommodate the result. See 9.4.1.4 of Chapter 17. 


var 
aStringS : string[5]; 
begin 
readstring('The input string has more than 5 chars', aString5); 
{ Error } 
end; 


Subrange boundaries are not of the same type. 


Two constants in a subrange definition must have compatible types. See 3.1.1.3 of Chapter 
17, Example: 


var 
SubrangeOfDifferentTypes : red..HEAVY; { Wrong 
GoodSubRange : red..yellow; { Right 
BadSet : set of red..HEAVY; { Wrong 

{ 

{ 


GoodSet : set of red..blue; Right } 
AlsoGoodSet : set of ColorType; Also Right }) 


Subrange boundary is not integer, char, or enumerated. 
See 3.1.1.3 of Chapter 17. 


type 
BadRealType = 2.5..3.1; { Error: real in subrange } 
{ is not allowed } 
var 
RealSubrange : 2.5..3.1; { Error: real in subrange } 


{ is not allowed } 
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Subrange error. 


The Range compile option inserts code which checks for out of range errors in your program 
(see Chapter 15). This runtime error occurs when this check has failed. Example: 


var 
Small. > 1...5 
Big : -20000..20000; 


begin 
anInt := 6; 
Small := anInt; { Error } 
Small := anInt - 3; { OK } 
anInt := 30000; 
Big := anInt; { Error } 
end; 


Superclass type must be object 


The heritage of an object must be another object. If you declare objects whose superclass is 
TObject, don’t forget to add ObjInt£.p to your project. 


program test; 


uses 
ObjIntf£; 
type 
TestObj = object (TObject) { CORRECT } 
end; 
BadTestObj = object (integer) { ERROR: integer isn’t an object } 
end; 
begin 
end. 


Tag type must be ordinal. 
See 3.1.1 and 3.2.2 of Chapter 17. 


type 
BadVariantRecordType = record 
case FloatingPointTag : Real of 
SeLALe -s. i¢ { Wrong: tag type can't be Real } 
Pi. + string|[2] 
Na 


end; 

GoodVariantRecordType = record 
case i: integer of 
ea { Right } 


Pi : string[2] 
de 
end; 
OKVariantRecordType = record 
case longTag : longint of 
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$12345 : ( { OK: tag type can be Longint } 
L : string[8] 
i 


end; 


The entire read will be re-executed when you continue. 


If you click on the Bug Spray Can while reading from the Text window with read or 
read1n, the read will stop and all pending input will be thrown away. When you continue 
the program, the entire read will be started over again. 


This declaration or statement doesn't belong here. 
See Setcion 8 of Chapter 17. Example: 


unit BadUnit; 


interface 
label { Error: Can't have a label here } 
0; 

implementation 
label { Error: Can't have a label here } 
ay 

end. 


This doesn't make sense as a statement. 


Everything between a begin and an end must be a statement. See 2.1 and 6 of Chapter 17. 
Example: 


program NonStatements; 
begin 
{ The following are illegal because they aren't statements. } 
inline 
string; 
aBool = false; { This is an expression, not an assignment } 
const 
unit bad; 
var 
type 
const 
end. 


This doesn't make sense. 


This error means that THINK Pascal finds something that doesn’t fit the syntax diagrams. See 
Chapter 17. Example: 


program; { Error: missing program name. } 
type 

StringType = string; 
var 
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BadArray : array[5] of char; { Wrong } 

GoodArray : array[1..5] of char; { Right } 

PointerToString : “string; { Wrong: Can't use STRING in } 
{ an anonymous type } 


PointerToString : *StringType; { Right } 
™ : Extended; { Wrong: can't use special characters } 
{ in identifiers } 

Pi : Extended; { Right } 
procedure ProcWithoutArgs; 
begin 

aChar := '%'; { OK: can use these set for strings & comments } 
end; 
begin 

anInt :=; Error: missing value } 


ProcWithoutArgs (); Wrong: Procs and Funcs without } 
args mustn't have ()} 
Right: It does look funny if you are } 


used to the C Language } 


ProcWithoutArgs; 


if true then 
writeln('Error: semicolon doesn’t belong at end of this line ->'); 
else { See 6.2.2.1 of Chapter 17 } 
writeln('OK: the problem is with the previous writeln'); 
writeln('Error: Missing close quote -> ); 
Error missing open comment } 
{ Error missing close comment 
end. 


This is not allowed in the Instant window. 


The THINK Pascal Instant window is special. It can execute any Pascal statement that would 
be legal at the point where your program is currently halted, except for gotos. See Section 6 
of Chapter 17. 


New declarations are not allowed. You might want to declare some scratch variables in your 
main program for use in the Instant window. 


This statement or keyword doesn't belong here. 
Possible misplaced or missing keywords. See 8.1, 2.1, and 8.3 of Chapter 17. Example: 


program BadProgram; 
writeln('BAD'); { Error: statements don't go in declaration part } 


i: integer; { Error: Need VAR before declaring variables } 

type 

t = integer; 

end; { Error: END doesn't go after TYPE declaration } 
begin 


end. { End of BadProgram } 
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Another example: 


unit BadUnit; 


interface 

label 

LS { Error: labels can't be made visible outside the unit } 
implementation 

label 

Rice { Error: labels can't be shared inside the unit } 


procedure empty; 
begin 
end; 

end. { End of BadUnit } 


Too few parameters used in procedure or function call. 
See 7.3 of Chapter 17. 


Too many constants in enumerated type. 


For efficiency, enumerated types are implemented as unsigned byte values ranging from 0 to 
255. Therefore, an enumerated type can have a maximum of 256 enumerated constants. 


Too many indices are being applied to a variable or expression. 


Array elements have to be accessed the same way in which they are declared. See 4.3 and 
4.3.1 of Chapter 17. Example: 


var 
OneDim : array[1..10] of integer; 
TwoDim : array[1..10, 1..10] of integer; 


begin 

OneDim[1][2] := 3; { Error } 

OneDim[1, 2, 3, 4] := 4; { Error } 

OneDim[3] := 5; { OK } 

TwoDim[1] [2] := 3; { OK } 

TwoDim[(1, 2] := 4; { OK: Pascal allows either form } 
end; 


Too many nested {$IFC} directives 
You can nest { $IFC)} directives only 16 levels deep. 


program test; 
begin 

{$IFC TRUE} 
{$IFC TRUE} 
{$IFC TRUE} 
{$IFC TRUE} 
{$IFC TRUE) 
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{$IFC TRUE} 
{$IFC TRUE} 
{$IFC TRUE) 
{$IFC TRUE} 
{$IFC TRUE} 
{$IFC TRUE} 
{SIFC TRUE} 
{$IFC TRUE} 
{SIFC TRUE} 
{SIFC TRUE} 
{$IFC TRUE} 
{$IFC TRUE} { ERROR: limit of 16 nested $IFC directives } 
writeln; 
end. 


Too many parameters used in procedure or function call. 
See 7.3 of Chapter 17. 


Too many up-arrows (4) are being applied to a variable or expression. 
Too many up arrows result in too many dereferences. See 4.3 and 4.3.4 of Chapter 17. 


type 

pType = “integer; 
ppType = “pType; 
var 

P : pType; 

pp : ppType; 

i: integer; 


begin 
anInt { Wrong } 
anInt { Right } 
anInt { Wrong } 
anInt { Right } 
end; 


Type expected. “symbol” isn't a type. 
See sections 3 and 4 of Chapter 17. Example: 


var’ 
NotAType : integer; 
s : set of NotAType; { Error: NotAType is not a type } 
i: NotAType; { Error: NotAType is not a type } 
BadArray : array[aConstant] of char; { Wrong: needs a type } 

{ or subrange } 

GoodArray : array[1l..aConstant] of char; { Right } 

type 
aBadType = NotAType; { Wrong } 


aGoodType = integer; { Right } 
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begin 
end; 


Type incompatibility between an actual and formal procedural or functional 
parameter. 


The functional or procedural parameter list must match the parameter list declared in the 
called subroutine. See 7.3.5 of Chapter 17. Example: 


procedure Pl (r : real); 

begin 

end; 

procedure P2 (x, y : integer); 

begin 

end; 

procedure CallP (procedure aProc (i : integer)); 

begin 

aProc (4); 

end; 

function F (i : integer) : real; 

begin 

end; 

procedure CallF (function aFunc (i : integer) : integer); 

begin 

writeln (aFunc (4) ); 

end; 
begin 

CallP(P1); { Error: Pl doesn't have same parameter types as aProc } 

CallP(P2); { Error: P2 doesn't have same number of args as aProc } 

CallF(F); { Error: F doesn't have same result type as aFunc } 
end; 


Type incompatibility between an actual and formal value parameter. 

Pascal requires assignment compatibility between actual value parameters (the actual 
expressions passed to a subroutine) and formal value parameters (the arguments in the 
subroutine definition). Assignment compatibility of types can be subtle. See 7.3.1 and 3.5.3 of 
Chapter 17. Example: 


type 
Canonical = array[1..4] of char; { a type } 
Indentical = Canonical; { an identical type with Canonical } 
AnotherType = array[1..4] of char; { type different from Canonical } 
var 
AnonArray : array[1..4] of char; { an array of an anonymous type } 
CanonicalArray : Canonical; { a variable of a named type } 
IdenticalArray : Indentical; { a variable of a same named type } 
AnotherArray : AnotherType; { a variable of a different named type } 


PAC : packed array[1..6] of char; 
procedure RealValue (r : real); 
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begin 
end; 
procedure IntValue (i : integer); 
begin 
end; 
procedure ArrayValue (a : Canonical ); { type of a must be named } 
begin 
end; 
begin 
RealValue (aReal) ; { OK } 
RealValue (anExt) ; { OK: anExt gets converted to real } 
RealValue (anInt) ; { OK: anInt gets converted to real } 
RealValue (aLong) ; { OK: aLong gets converted to real } 
Int Value (aLong) ; { OK: aLong gets converted to integer } 
IntValue(aColor) ; { Error: enums don't get converted to integer } 
IntValue (aReal) ; { Wrong: reals don't get converted to integer } 
IntValue(round(aReal)); { Right } 
IntValue(aPtr) ; { Error } 
anInt length ('string'); { OK } 
anInt length(aChar); { OK: aChar is treated as a string } 
anInt length (PAC) ; { OK: PAC [1..N] is treated as a string } 
anInt length (AnonArray); { Error: unpacked arrays don't } 


{get converted } 
{ These examples are subtle - see 3.5.1 of Chapter 17 } 
ArrayValue(CanonicalArray); { OK } 
ArrayValue(IdenticalArray); { OK: the types are identical } 
ArrayValue (AnonArray) ; { Error: anonymous types aren't } 
{ identical with anything} 
ArrayValue(AnotherArray); { Error: the named types are different } 
end; 


Type incompatibility between an actual and formal VAR parameter. 


Pascal requires the types of actual var parameters (the variable passed to a subroutine) and 
the types of formal var parameters (the arguments in the subroutine definition) to be 
identical. When a parameter is passed to a formal var parameter, the called subroutine can 
change the actual parameter passed, not just a copy of it. Therefore, the data representation 
of the actual parameter must exactly match the data representation of the formal parameter. 
Type identity can be sublle. See 7.3.2 and 3.5.1 of Chapter 17. 


type 
Canonical = array[1..4] of char; { a type } 
Indentical = Canonical; { an identical type with Canonical } 


SomeType = array([1..4] of char; { type DIFFERENT from Canonical } 
var 
AnonArray : array[1..4] of char; { an array of an anonymous type } 


CanonicalArray : Canonical; { a variable of a named type } 
IdenticalArray : Indentical; { a variable of a same named type } 
SomeArray : SomeType; { a variable of a different named type 


PAC : packed array[1..6] of char; 
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procedure RealVar (var r : real); 
begin 

end; 

procedure IntVar (var i: integer) ; 
begin 

end; 

procedure StringVar (var s : string); 
begin 

end; 

procedure ArrayVar (var a : Canonical ); { type of a must be named } 
begin 

end; 


begin 
RealVar (aReal) ; 
RealVar (anExt) ; 
RealVar (anInt) ; Error } 
RealVar (aLong) ; Error } 


{ OK } 
( 
{ 
{ 
IntVar (anInt) ; { OK } 
{ 
{ 
{ 
{ 


Error: types must match exactly for VAR } 


IntVar (aColor) ; Error } 
IntVar (aLong) ; Error } 
IntVar (aReal) ; Error } 
IntVar (aString) ; Error } 
IntVar (aPtr) ; { Error } 
StringVar (aString) ; { OK } 
StringVar(aString25); { OK: any string type is identical to } 

{ type VAR s:STRING } 
StringVar (aChar) ; { Error } 
StringVar (PAC) ; { Error } 
StringVar(AnonArray); { Error: unpacked char arrays } 

{ don't match strings } 
{ These examples are subtle - see 3.5.1 of Chapter 17 } 
ArrayVar (CanonicalArray);{ OK } 
ArrayVar (IdenticalArray);{ OK: the types are identical } 
ArrayVar(AnonArray); { Error: anonymous types aren't } 

{ identical with anything } 
ArrayVar (AnotherArray); { Error: the named types are different } 

end; 


Type incompatibility. 


You can't add apples and oranges. Pascal catches illogical statements that try to use 
incompatible types. On occasion, this rule need to be broken. The following examples show 
common errors and methods to break the rules. Use the methods at your own risk. Type 
compatibility can be subtle. See 3.5.2 and 5 of Chapter 17. Example: 


var 
PtrToInt : “integer; 
PtrToChar : “char; 

begin 
aBool := (aColor = 1); { Wrong: can't compare } 
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{ incompatible types } 
aBool := (Ord(aColor) = 1); { Right: but what do you } 
{ really want to do? } 


aBool := (aColor = ColorType(1)); { Also Right: but what do } 
{you really want to do? } 
aBool (aString = aChar); { OK to compare strings to char } 
aBool (aString = anInt); { Wrong: strings and integers } 
{ aren't compatible } 
aBool := (aString = stringof(anInt : 1)); { Right: anInt is } 


{ converted to a string } 
aBool 
aBool 


= (red in [(red..violet]); 
= (2 in [red..violet]); 


{ Right } 
{ Wrong: 2 isn't in } 
{ set of ColorType } 
aBool := (red in [red..violet]); { Right } 
aBool := ('a' in [SOD..'z']); { Wrong: $0D is a different } 
{ 
{ 
{ 
{ 
{ 


type from 'z' } 
Right: chr($O0D) is } 
a carriage return } 
Wrong: pointers are of } 
different types } 
(pointer (PtrToInt) = PtrToChar); {Right: but what } 
{do you really want to do?} 


aBool := ('a' in [chr($0D)..'z']); 


aBool := (PtrToInt = PtrToChar) ; 


aBool 


i] 


end; 


Type or procedure name used where a variable, field name, or value is required. 
See Sections 5 and 6 of Chapter 17. Example: 


type 
aType = integer; 
aName = integer; 
var 
aRecord : record 
aName : integer 
end; 


procedure aProc; 
begin 
end; 
begin 
anInt := aName; { Error: aName refers to a type in this statement} 
iff anInt = aType then { Error: aType is not a value } 


with aRecord do 


begin 
anInt := aName; { OK: aName refers to field in } 
{ aRecord in this statement } 
aniInt aProc; { Error: aProcedure is not a value } 
anInt aType; { Error: aType is not a value } 
end; 


end; 
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Unexpected end of file. 


EOF (End Of File) was reached while doing a Read. You should always check for EOF before 
reading. See 9.9 of Chapter 17. Example: 


RESET (FileOfText, ‘input file'); 

while true do { Error: eventually tries to read past end of file } 
readin (FileOfText, aString); 

close (FileOfText) ; 

RESET (FileOfText, ‘input file'); 

while not eof (FileOfText) do { Right: checks for EOF } 
readln(FileOfText, aString) ; 


USES only allowed immediately after PROGRAM heading or INTERFACE. 
See 8.1 and 8.3 of Chapter 17. Example: 


program WhichUsesUnits; 
uses 

aUnit; { Right } 
var 

i: integer; 
uses 

AnotherUnit; { Wrong } 
begin 
end. 


Variable or function name expected. “symbo!” isn't a variable or function. 


The target of an assignment must be a variable or a function name when a return result is 
being set. See 6.1.1 and 7.2 of Chapter 17. 


type 

NotAVariable = integer; 
var 

aVariable : integer; 

aPtrToInteger : “integer; 
procedure aProcedure; 


begin 
end; 
function aFunction : integer; 
begin 
NotAVariable := 4; { Wrong: NotAVariable is not a variable } 
aVariable := 4; { Right } 
aPtrToInteger® := 4; { Also Right } 
aProcedure 4; { Wrong: aProcedure is not a function name } 
aFunction ; { Right: this is how functions return values } 
end; 
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Variables of a file type or a type which contains a file type can't be assigned. 

For every open file, there must only be one copy of the file-variable. The operating system 
needs file-variables for file input/output. If a copy of the file-variable could be made, and 
both were used for file I/O, then the file would be inconsistent. Therefore, making a new 
copy of a file-variable is forbidden. Example: 


var 
file 1, file 2 : file of integer; 
array _1, array_2 : array[1..3] of file of integer; 
record 1, record 2 : record 
FileName : string; 
FileParameter : file of real; 


end; 
begin 
open(file 1, 'My file'); 
Filed Eile 2; { Error: could cause havoc with filesystem } 
close (file 2); { especially, if you did this } 
array 1 := array 2; { Error: these arrays contain filetypes } 
record 1 := record 2; { Error: these records contain filetypes } 


end; 


Variables of this type would be too large. 


Because THINK Pascal use 16 bit offsets (the MC68000 architecture doesn't allow 32 bit 
offsets), a data structure cannot exceed 32766 bytes. 


rec = record 
ar : packed array [0..40000] of char; 
sp : integer; 
end; 


Variant-part of record contains no variants. 
See 3.2.2 of Chapter 17. Example: 


type 
BadVariantRecordType = record 
case tag : integer of 
{ Error: must have at least one variant here } 
end; 


While your program is halted, you may not manipulate your program's windows. 


While your program is halted, your code, which handle events in your program's windows, is 
not running, so you can’t manipulate your program’s windows. 
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Writing over a project or library is not allowed. 


This is a safety feature that prevents you from overwriting a project or library by accident. 
You can delete the project or library with the Delete command in the File menu. 


You already have a window named “Name1”. Would you like to open your file as 


“Untitled N”? 


You may have tried to open a file twice. You may have two different files with the same, 
name but in different volumes or folders. At this point, you can either open the file and see 
what's in it, or you can cancel. 


program InputAndOutput (input, output); 


begin 
reset (output) ; { Wrong } 
reset (input) ; { Right } 
rewrite (input) ; { Wrong } 
rewrite(output); { Right } 
end. 


You can’t CLOSE an anonymous file. 


Unnamed files are sometime also referred to as anonymous files. See 9.1 and 9.2.4 of Chapter 
17. Example: 


var 
fo : Text; 
begin 
rewrite(f); { Associate an unnamed file with f } 
close(f); { Wrong: can't close an unnamed file } 
end; { When the scope the file variable is exited, f will be closed } 


{$ELSEC} or {$ENDC} has no matching {$IFC} 
Every { $ELSEC} or {SENDC)} must have a matching { $IFC} 


program test; 
begin 
{S$SETC compiler_var = false} 
{$IFC compiler var} 
writeln('This line will not be compiled’); 


{ SELSEC} 
writeln('This line will be compiled’); 
{ SENDC} 
{ SELSEC} { ERROR } 
{ SENDC} { ERROR } 
end. 
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Introduction 


This appendix introduces you to the Macsbug debugger. The Macsbug debugger is a low- 
level debugger that lets you look at the assembly language code of your program. Of course, 
most of the time you'll just use THINK Pascal's high-level debugging tools, but sometimes 
you just need to get a little close to the machine. 


Before you begin 

To get the most out of Macsbug, it helps if you know some MC68000 assembly language. You 
don’t need to know everything about assembly language, just the fundamentals. If you’re the 
adventurous sort, you'll learn a lot about assembly language when you use Macsbug. 


Topics covered in this appendix 
¢ Installing Macsbug 
¢ Using Macsbug 
¢ Program execution control 
e Set and display commands 
° Expressions 
e A-Trap commands 
e Program termination 
¢ Heap zone commands 
* Miscellaneous commands 
¢ Tips 


Installing Macsbug 


To install Macsbug into your machine, just drag the Macsbug document from disk THINK 
Pascal # to your System Folder. Then use the Restart command from the Finder's Special 
menu to reboot your Macintosh. 


You'll know Macsbug is installed when, in addition to the “Welcome to Macintosh” message, 
you see the message “Macsbug installed.” 


The Macintosh expects the debugger to be named Macsbug, so if you don’t want Macsbug 
installed when you boot, you can just rename the file to something other than Macsbug. 
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Using Macsbug 


Macsbug takes control of your Macintosh when one of three things happens: 


¢ You press the interrupt switch — the rear-most switch in your programmer's switch. 
* Whenever you would get a system error (a bomb). 
¢ Whenever your program executes a Debugger or DebugStr trap. 


When a system error occurs, Macsbug displays the error, and you'll see a > prompt. There are 
some system errors which will still give you the “bomb” dialog box. Most of the time you can 
hit the interrupt button to get into Macsbug from there.) On other breaks, Macsbug will 
display the machine state — the program counter (PC), the current instruction, the status reg- 
ister (SR), the data registers (D0 through D7), the address registers (AO through A7) and 
prompt you for a command with a >. 


Program Execution Control 


Ga Go 
Resume program execution at address a. If a is 
omitted, the program resumes at the value of the PC. 
T Trace 
Execute one instruction (treats A-Traps as one instruc- 
tion) 


Sn Step 
Execute n instructions (n defaults to 1), step into A- 
Traps. 


BRan BReakpoint 
Interrupt program execution the n-th time the PC 
reaches a (n defaults to 1). Up to six breakpoints may 
be active at a time. 


CLa CLear 
Clear the breakpoint at address a. If a is omitted, CL 
clears all breakpoints. 


GT a GoTill 
Interrupt program execution the next time the PC 
reaches a 

ST. .a Step Till 


Step through instructions until the PC reaches a 


MR Magic Return 
Execute until the PC reaches the address on the top of 
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the stack. Most useful when issued just following a JSR 
or BSR, to return to the instruction after the call. 


Note: BR, GT, and MR won't work if the target address is in ROM. To break 
in ROM you must use ST. 


Set and Display Commands 


DM an Display Memory 

Starting at address a, display n bytes (n defaults to $10 
(hex 10)). n may alternatively take one of three four- 
character string values, and the data is displayed 
accordingly. These possible values for n are: 

‘IOPB' - display as I/O parameter block 

'WIND' - display as window record 

'TERC! - display as text edit record 


SM av _v v.. Set Memory 
Starting at address a, replace memory by values v. 


Dn v Data Register 
Sets data register n to value v. If v is omitted, displays 
the data register value. 


An v Address Register 
Sets address register n to value v. If v is omitted, dis- 
plays the value in the address register. 


Fnv Floating point register 
Sets floating point register to v. If v is omitted, displays 
the value of the floating point register, 


PC. Vv Program Counter 
Sets the PC to value v . If v is omitted, displays the 
value of the PC. 


SR v Status Register 
Sets the SR to value v. If v is omitted, displays the 
value of the SR. 


TD Total Display 
Displays the next instruction to execute, all the registers, 
the PC and SR. 


ILan Instruction List 
List the next n instructions beginning at address a. If n is 
missing, it defaults to 14. 
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IDa Instruction Disassembly; disassemble and display the 
instruction at address a. 


Expressions 


Wherever a command accepts an address or a value an expression may be substituted. The 
following notations are used in Macsbug expressions: 


+ Addition 

= Subtraction 

j Last address given to DM, SM, IL or ID 
RAn The value in address register n 

RDn The value in data register n 

@ “Contents of” operator 

$ Interpret following integer as hexadecimal (default) 
# Interpret the following integer as decimal 
PC The value of the PC 

Taeseats, The value of the given string 

< Sign-extend the following to 32 bits 


Macsbug understands trap names. A trap name evaluates to its trap number. In addition, if 
you are examining code that was compiled with the N (Names) compile option on, you may 
use your THINK Pascal function names in expressions. For more details, see Chapter 9, and 
Chapter 15. 


A-Trap Commands 


These commands monitor the 68000 A-Trap instructions, which are used to invoke Macintosh 
Operating System and Toolbox routines in the ROM. These commands all begin with the let- 
ter A and take up Lo 6 parameters: 


<command> Tl T2 Al A2 D1 D2 


T1 and T2 indicate the range of A-Traps to monitor. 
Al and A2 specify the address range which to monitor for A-Trap calls. 
D1 and D2 specify the range in which DO must be for the break to occur. 


All of these parameters are optional. If both T1 and 12 are absent, T1 defaults to 0, T2 to 
$1FE (all traps). If T1 is the only argument, the command is only active for that trap. Al de- 
faults to 0, A2 to the top of memory, D1 to 0 and D2 to $FFFFFFFF. 


In using the A-Trap commands, the trap numbers T1 and T2 are actually the low order 9 bits 


of the trap instruction. For instance, to break on the trap $A97D (NewDialog), use the value 
$17D. To make things easier, you can use the trap name instead of the number. 
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AB breaks into Macsbug when the conditions are met 

AT traces the A-Traps meeting the conditions 

AH does an HC (see below) before executing the rap when 
conditions are met. T1 must be at least $2F 

AR remembers the last A-Trap which met the given condi- 
tions. Use AR without arguments to list the trap remem- 
bered 

AX clears all A-Trap commands 


Program Termination 


RB ReBoot 
Restart the Macintosh. See the “Tips” section at the end 
of this appendix for a better way to restart your 
Macintosh. 

ES Exit to Shell 
Returns to the Finder (or to THINK Pascal). 


EA Exit to Application 
Relaunches the current application. 


Heap Zone Commands 


HD mask Heap Dump 


Displays a list of all blocks in the current heap. The dis- 
play format is: 


addr type size [flags pointer] [*] [refnum id type] 


mask is optional. It limits the heap display and sum- 
mary to those blocks which satisfy the condition in the 
mask. Possible values for the mask are: 


'H' : display handles only 

'p': display pointers only 

'F': display only free blocks 

'R': display only resource blocks 

'xxxx': display only blocks of the given resource type 


HT mask Heap Total 
Displays a heap summary line for the mask given. The 
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HC 


HX 


format of the summary line is: 


HLP PF #handles #locked #purgeable total-size-of- 


purgeable-blocks #pointers free-space 


Heap Check 
Checks the consistency of the heap. 
Note: HC will hang if the heap is badly damaged. 


Heap eXchange 
Toggles the heap display between system and applica- 
tion heaps. 


Miscellaneous Commands 


Fandm 


WH 


cv 


cs 


ss 


AS 


al a2 


al a2 


Al A2 


Find 
Starting al address a, search n bytes for data d, after 
masking the data with m. 


WHere 

If a is less than 512, give the PC at which the trap code 
resides. Otherwise, display the trap and trap starting ad- 
dress which is closest to a . 


ConVert 

Displays a in unsigned hexadecimal, signed hexadeci- 
mal, signed decimal and text. When used with expres- 
sions, you have an all-purpose programmer's calculator! 


CheckSum 

Does a checksum of the address range al. .a2. When 
no arguments are present, it returns CHKSUM_T if the 
checksum of the last given range is the same as when it 
was last calculated, CHKSUM F otherwise. 


Step Spy 

Does a checksum of the contents of the address range 
al..a2 between the execution of each instruction. 
Breaks when the checksum changes. 

Note: This command is very slow, but very useful. Disk 
access doesn't work well with SS active. 


A-Trap Spy 
Similar to SS, but calculates the checksum before each 
A-Trap. (This command is cancelled by Ax.) 
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sc Stack Crawl 

This command assumes that LINK and UNLK instruc- 
tions appear at the beginning and end of each function 
(generally true in THINK Pascal). It returns a list of the 
active stack frames and their return addresses. This is 
useful to see who called what and where. (Hint: If you 
are al a LINK instruction, step beyond it before you do 
SE) 


SX Symbol eXchange 
Toggles the visibility of procedure names in IL and ID 
commands. Defaults to enabled. 


RX Register eXchange 
Toggles the visibility of the register dump during tracing 
and stepping. Defaults to enabled. 


DX Debugger eXchange 
Toggles Debugger trap entry. When enabled, calling 
Debugger () or DebugStr() will break into 
Macsbug; otherwise it won’t cause a break. Defaults to 
enabled. 


SD Symbol Dump 
Dumps the names of all the symbols known to 
Macsbug. 


Tips 
Typing the Return key usually repeats the previous command. After an IL or ID command, 


typing Return displays the next instructions. After DM typing Return displays the next mem- 
ory locations. After an MR command, it will execute a T (Trace). 


Holding down the Backspace key while a Macsbug command is listing cancels the command. 
Holding down the space key pauses the listing. Typing the space key again restarts it. 


Hitting the * key (at the top left of the keyboard) while in Macsbug toggles the display be- 
tween the Macsbug screen and the program’s screen. 


Sometimes you will break into Macsbug with the disk still spinning. To stop the disk, enter 
DM DFF1FF. This will hit the Woz machine (disk drive controller) address that stops the 
disk. 


The word $471 is the NOP instruction. If you want to take instructions out of your program, 
use this word to NOP out instructions in your code stream. 
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Note: The NOP is a two byte instruction. If the instruction you are going to 
NOP is longer than two bytes, remember to use enough NOPs to clear out 
the whole instruction. 


The best way to reboot your Macintosh is to use the Shut Down Manager. Here’s one way to 
do that: 


SM 0 3F3C 0002 A895 
G0 


This technique is usually safer than using the RB command. 


Entries in bold face refer to menu commands. 


Index 


Entries in typewriter face refer to procedures or functions. 


.0 files 88, 203 
-Rel files 157 
@ operator 244, 264 


AS world 149 

About THINK Pascal... 193 

abs 328 

activation 226 

activations 228-229 

Add File... 88, 114, 157, 203 

Add Window 88, 203 

anonymous file 302 

APDA 8 

Apple Numerics Manual, Second Edition 8, 
234 

AppleTalk 122 

application globals 149 

application parameters 149 

arctan 330 

arithmetic operators 232, 258 

array representation 151 

array-type 236 

arrays 249 

arrow keys 74 

assembly language 147-157 

assignment compatibility 246 

assignment-statement 268 

Asynch compiler directive 185 

Auto-Reformat 72, 199 

Auto-Save 100, 211 

Auto-Show Finger 105, 214 


BAND 337 
base-type 241, 243 
BCLR 339 
Beekman, George 7 
BInlineF 344 
BitAnd 336 
BitNot 337 
BitOr 337 


BitXor 337 

blocks 225 

BNOT 338 

boolean 232 

boolean operators 260 
boolean representation 150 
BOR 337 

Break at A-Traps 174, 214 
BROTL 338 

BROTR 338 

BSET 339 

BSL 338 

BSR 338 

BTST 339 

Build 99, 210 

Build Application... 146, 204 
Build Code Resource... 146, 204 
Build Desk Accessory... 146, 204 
Build Driver... 146, 204 
Build Library... 115, 203 
build order 89 

Bundle bit 127 

BXOR 338 


callback routines 

in drivers 133 
calling conventions 152-155 
calling sequence 152 
case label subranges 365 
case-constants 276 
case-statement 276 
char 232 
char representation 150 
character-string 223 
Check 99, 210 
Check Link 97, 99, 210 
Chernicoff, Stephen 8 
chr 331 
Clancy, Michael 7 
Clear 198 
Clipboard 216 
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Close 78, 194 
Close Project 88, 203 
close 305 
closing files 78 
code resources 

global data in 143 
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locking 144 

writing 143 
coercion 267 
collected views 167 
comments 224 
Compile Options... 187, 208 
compile-time variables 186 
compiler directive 177 
compiler options 90, 177, 225 
completion routines 185 
component-type 236, 241 
compound-statement 274 
CompuServe 8 
computational 235 
concat 332 
conditional compilation 186 
conditional-statement 274 
Confirm Saves 100, 211 
constant expressions 364 
constant-declaration 224 
constant-declaration-part 226 
Consulair Development System 157 
control-variable 279 
Cooper, Doug 7 
Copy 197 
copy 333 
cos 330 
Cut 197 
Cycle 340, 364 


DA Shell 139 
data type representation 149-152 
data types 149 
Debug compiler directive 181 
Debugger 346 
DebugSt r 346 
declaration-part 225 
defining-declaration 285 
delete 333 
Delete... 196 
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running 139 

writing 132 
device drivers 


writing 132 
devices 321 
directives 221 
dispose 324 
Don’t Save 100, 211 
double 235 
double representation 150 
Drawing 216 
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global data in 133 
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returning 137, 138 
writing 132 
DRVRRuntime.lib 119, 131, 134, 143 
dynamic-variables 243, 252 


Echo to file 102 
Echo to printer 102 
editing variables 168 
empty set 241 
Enter Selection 201 
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enumerated types representation 150 
enumerated-type 233 
eof 305 
eoln 317 
Exit (procName) 340, 364 
exp 330 
expanded view 165 
expression 257 
expressions 253-267 
constant 364 
in constants 224 
Extended Keyboard 74 
extended 235 
extended representation 150 
external 117 
external declaration 286 


factor 254 
fields 238, 251 
File Windows 216 
file representation 152 
file-buffer 252, 303 
file-type 241 
file-variable 252 
filepos 307 
files 88 

-rel files 157 


closing 78 

creating 69 

editing 71-76 

opening 69 

saving 78 
files 302 
Find Again 77, 200 
Find in Next File 78, 200 
Find... 76, 199 
fixed-part 238 
for-statement 279 
formal-parameter-list 290 
forward declaration 285 
function calls 265-266 
function-declaration 288 
function-heading 288 
functional parameters 291, 296 
functions 284-296 


Generic 345 

get 306 
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Get TextRect 335 

Go 95, 211 
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goto-statement 271 
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heap 148 
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HideA11 335 
HiWord 339 
HiWrd 339 
host-type 234 
How to Write Macintosh Software 8 
Howe, Greg 431 


identifiers 221 
if-statements 275 
implementation 112 
implicit parameters 296 
include 334 
index-type 237 
indices 249 
InitFPState 185 
Initialization compiler directive 184 
initialization 

automatic 184 
inline declaration 287 
InlineP 344 


input/output 301 
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Instant window 104, 110 
integer 231 

integer representation 150 
interface 112 

interface file 114, 115 
IOCheck 322 
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Johnson, Michael 7 
jump table 149 
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Knaster, Scott 8 
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lazy I/O 318-321 
Leave 340, 364 
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of string-types 243 
libraries 114 
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in code resources 144 
in drivers 135 
interface files 115 
standard 119 
using 114 
writing 115 
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Macintosh Toolbox 

calling 120-124 
MacTutor 8 
maxint 231 
maxlongint 232 
MC68020 option 190 
MC68881 150 
MC68881 option 189 
McGarry, Carol E. 83, 112 
Member (r, t) 346 
memory display 172 
memory 

editing 173 
method-designator 270 
methods 241 
modem 321 
Monitor 214 
MPW 88, 156, 203 
multi-file search 78, 200 


Names compiler directive 181 
New 69, 194 

New Project... 87, 202 

new 244, 323 
NewFileName 343 

nil 244 

Note 343 

null-string 243 

numbers 221 


Object Pascal 
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Object-Oriented Programming 
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object-type 241 
Observe 216 
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OldFileName 343 

omit 334 

Open Project... 87, 202 

open 305 

Open... 69, 194 

operands 253 

operators 253, 257-265 
@ 264 


arithmetic 232, 258 
boolean 260 
boolean 365 
order of evaluation 257 
set 261 
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compile-time variables 188 
compiler 90 
MC68020 190 
MC68881 189 
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save 80, 100 
search 76 
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ord 331 
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ordinal-types 231 
comparing 262 
standard 231 
otherwise 276 
Overflow compiler directive 182 
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pack 325 
packed-string-type 237 
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parameter passing 154 
parameters 290 
parameters lists 296 
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Paste 197 
pointer representation 150 
pointer-type 243 
pointers 252, 263, 328 
pop-up menus 

routine names 75 

unit names 70 
pos 332 
precedence rules 253 
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of real-types 235 
pred 331 
predecessor 231 
predefined routines 119-124 
pretty-printing 80 
printer 321 


Printing Manager 123 
printing 78 
Print... 78, 196 
procedural parameters 291, 292 
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declaration-part 226 

procedure-declaration 284 
procedure-statement 270 
procedures 284-296 
program parameters 298 
program syntax 297 
programs 297-301 
Project name 215 
project type 126 
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removing files 88 
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put 306 
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read 307, 310 
readin 313 
ReadString 342 
real 235 
real representation 150 
real-types 234 

comparing 262 
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record representation 151 
record-type 238 
records 251 
recursion 228 
reference variable 242, 252 
reference-type 242 
reference-variable 252 
references 241 
register saving 154 
registers 
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RememberA4 134 
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resource files 101 
resources 
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RestoreA4 134 
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rewrite 304 
round 327 
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routine exit 153 
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SaveDrawing 336 sqrt 329 
saving files 78 stack 148 
Schmucker, Kurt 7 stack frame 148 
scope 227-228 stack size 102 
declarations of identifiers 227 standard libraries 119 
in LightsBug 164 stalement-part 225, 226 
of a declaration 227 statements 268-284 
of field 228 Step 106, 211 
of interface identifiers 228 Step Into Calls 105, 214 
of standard identifiers 228 Stop Signs 106 
redeclarations 227 Stops In 107, 214 
searching 76-78 string representation 151 
multi-file 78 string-type 243 
searching length attribute 243 
multi-file 200 size attribute 243 
seek 307 string-types 237 
Segment Loader 89, 149, 363 comparing 263 
Select All 198 ordering 243 
selector 276 StringOf 342 
self 296 strings 249 
separators 219 StripAddress 151 
Serial Driver 123 structured-statements 273 
Set of integer option 190, 208 structured-type 236 
Set Project Type... 126, 204 subrange-type 234 
set membership 263 subroutine call chain 162 
set operators 261 subroutines 
set representation 151 examining 162 
set-constructors 266 succ 331 
sel-type 241 successor 231 
set-types Synch 343 
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SetUpA4 134 
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type 229 writeln 317 
type casting 169 

type coercion 240 
type compatibility 245 
type identity 244 
type-casts 267 
type-declaration 229 HRuntime.lib 119 
type-declaration-part 226, 247 

types 229-247 


zone 148 
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Undo 73, 197 
unit syntax 298 
units 111-114, 297-301 
opening 70 
unit dependencies 300 
using 111 
writing 112 
UnloadA4Seg 139 
unpack 326 
unsigned-constant 255 
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value parameters 291, 292 
variable display 164 
variable parameters 291, 292 
variable-declaration 247 
variable-declaration-part 226 
variable-reference 248 
variables 247-252 
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editing 168 
examining 164 
examining structured variables 165 
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vertical retrace tasks 185 
Vetri, Paul 431 
View Options... 92, 112, 209 
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windows 70 
WinlineF 344 
Wirth, Niklaus 7 
with 251 
with-statement 282 
write 308, 314 
WriteDraw 341 
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License Agreement 


License Agreement 


This manual and the software described in it were developed and are copyrighted by 
Symantec Corporation (Symantec) and are licensed to you on a non-exclusive, non- 
transferable basis. Neither the manual nor the software may be copied in whole or in part 
except as follows: 


1) You may make backup copies of the software for your use provided that they bear 
Symantec’s copyright notice. 


2) You have the right to include object code derived from the libraries in programs that you 
develop using the software and you also have the right to use, distribute and license such 
programs to third parties without payment of any further license fees, so long as a copy- 
right notice sufficient to protect your copyright in the software in the United States or any 
other country is included in the graphic display of your software and on the labels affixed 
to the media on which you software is distributed. 


You may not in any event distribute any of the source files provided or licensed as part of the 
software. You may use the software at any number of locations so long as there is no pos- 
sibility of it being used at more than one location at a time. 


Symantec’s Plain Language License Statement 


Symantec is concerned with how you copyright your software only in the case where you 
use object code of libraries which Symantec provides in source form These libraries may be 
included in your program so long as a copyright notice that will protect your copyright in the 
software is in the “About box” of your software and on the disk labels, as specified in the 
license agreement. You are not required to include a specific Symantec copyright notice 
except if your copyright does not satisfy the above requirement. This is only an explanation 
of the License Agreement. All terms and conditions of the License Agreement apply. 


Limited Warranty on Media and Manuals 


If you discover physical defects in the media on which this software is distributed or in the 
manuals distributed with the software, Symantec will replace the media or manuals at no cost 
to you provided that you return the defective materials along with a copy of your receipt to 
Symantec or to an authorized Symantec dealer during the 60-day period following your re- 
ceipt of the software. 


Limited Warranty on the Product 


Symantec warrants that the software will perform substantially as described in the User's 
Manual. If within 60 days of receiving the software, you give written notification to Symantec 
of a significant, reproducible error in the software which prevents operation, and provide a 
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written description of the possible problem along with a machine readable example, if ap- 
propriate, Symantec will either provide you with corrective or workaround instructions, a 
corrected copy of the software, a correction to the User’s Manual, or Symantec will refund 
your purchase price upon return of all copies of the software and documentation together 
will a copy of your receipt. This warranty extends only to you and shall be void if the 
software has been tampered with, modified, or improperly used, or if the software is used on 
hardware other than the Apple Macintosh™ Computer. 


EXCEPT FOR THE LIMITED WARRANTY DESCRIBED ABOVE, THERE ARE NO WAR- 
RANTIES TO YOU OR ANY OTHER PERSON OR ENTITY FOR THE PRODUCT EXPRESSED 
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OR MER- 
CHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. ALL SUCH WARRANTIES ARE 
EXPRESSLY AND SPECIFICALLY DISCLAIMED. Some states do not allow the exclusion of 
implied warranties or limitations on how long they last, and you also may have other rights 
that vary from state to state. INNO EVENT SHALL SYMANTEC BE RESPONSIBLE FOR ANY 
INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR SIMILAR DAMAGES OR LOST 
DATA OR PROFITS TO YOU OR ANY OTHER PERSON OR ENTITY REGARDLESS OF THE 
LEGAL THEORY, EVEN IF WE HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH 
DAMAGE. Some states do not allow the exclusion or limitation of incidental or consequential 
damages, so the above limitation or exclusion may not apply to you. The warranty and 
remedies set forth are exclusive and in lieu of all others, oral or written, express or implied. 


SYMANTEC MAKES NO WARRANTY OF THE PERFORMANCE OF THE LIBRARIES WHEN 
USED IN YOUR SOFTWARE. YOU AGREE TO INDEMNIFY SYMANTEC FROM ALL CLAIMS 
BY THIRD PARTIES ARISING IN CONNECTION WITH THE USE OF YOUR SOFTWARE. 


General Terms This license states the entire agreement between the parties and supercedes 
all other communications between the parties relating to this License, which shall be gov- 
erned and construed in accordance with the laws of the State of California. You agree to 
bring any proceeding to enforce or consuue this License or involving the performance of the 
software only in a federal or state court residing in the State of California. The prevailing party 
in any such proceedings shall be entitled to recover its attorneys’ fee and litigation expenses 
in addition to other appropriate relief. If any provision of this License by Symantec shall be 
held to be unenforceable such holding shall not affect the enforceability of any other 
provision hereof. Waiver of any breach of this License by Symantec shall not be considered a 
waiver of any other or subsequent breach. the licensed software is a unique and valuable 
asset of Symantec and Symantec has the right to seek whatever equitable and legal redress 
which may be available to it for your breach of the provisions of the License. 


“Lightspeed” is a trademark of Lightspeed, Inc., and is used with its permission. 


SYMANTEC 


SYMANTEC. 


10201 Torre Avenue 
Cupertino, CA 95014 


